API Reference

Substrate Reasoning (/api/reason)

The substrate reasoning endpoint runs the full translation sandwich (Layer 1 feature extraction, the deterministic signed Layer 2 assessment, and Layer 3 prose). It is governed by the per-loop model (see the access tiers above) and supports, beyond the standard request body:

• Deferred prose — response_format is full (the default, assessment and narrative prose in one response) or assessment_first (the signed assessment, extraction, and meta return immediately; the response carries a narrative object with status: deferred and a correlation_id, plus meta.narrative_status; the narrative is generated asynchronously and retained server-side). Deferral is a request, not a guarantee — consults carrying a distress signal always return the full synchronous shape.
• The narrative must exist — a verdict without a narrative account is a classification, not an examination. assessment_first moves generation out of the response path; it never suppresses it. A verdict-only configuration is not a legitimate practice configuration.
• Open Layer 1 — supply a layer1_schema that validates against the documented contract to skip server-side Layer 1 (meta.layer1_source: supplied, layer1_latency_ms: 0). It is optional on sr_live_ and sr_prac_, required on sr_inst_, and requires the l1_supplycapability (otherwise 403). Omitting it keeps raw-text behaviour (meta.layer1_source: server); a malformed schema returns 400. The input text is always required — the safety perimeter runs on the text regardless of who computed the schema.
• Trajectory overlay & practice delta — credential-bearing consults carry a meta.trajectory overlay (the presenting credential’s windowed history) with a meta.trajectory.delta block (agent-trajectory-delta-v1): per-mechanism, evidence-floored, evaluative-never-predictive practice deltas. Read-and-describe — the signed assessment is unchanged. MEASURE-only; weights-tier use is blocked.
• Retention (R17) — retained narratives and their paired signed assessments are stored encrypted at rest, for 90 days, keyed by correlation id; genuine (hard) deletion is available on request.
• Re-examination (prior_feedback) — an optional object { prior_loop_id, prior_depth_tier, adopted_correction? } that carries a re-examination back to a prior consult. prior_loop_id is the prior consult's assessment.examination.ref (its X-Loop-Id); the re-examination carries the prior depth (the same-depth rule). The response surfaces examination_open and places examination.{ ref, depth_tier, prior_feedback_ref } inside the signed assessment. A malformed prior_feedback returns 400.
• Dikaiosyne weighting (justice in the proximity) — katorthoma_proximityis the minimum across the engaged cardinal-virtue domains (the unity thesis — a strong domain does not compensate for a weak one), so a calmly-reasoned injustice scores reflexive, not near-virtuous. The signed assessment.assessment carries proximity_floors { base, dikaiosyne, andreia, sophrosyne, aggregate, basis } — base (the disposition/apatheia reading) floored by the per-domain readings (null = that domain was not engaged); aggregate === katorthoma_proximity. When an oikeiosis circle is engaged, each oikeiosis.relevant_circles[] entry carries an obligation_assessment { status: met|violated|indeterminate, justification } that resolves the dikaiosyne domain (violated → reflexive; indeterminate → capped at deliberate; met → no floor). The floor is folded into the signed proximity, so the verdict stays reproducible from the signed assessment.
• Practice suggestions (advisory) — an emitted practice block may carry an optional suggestion member (agent-practice-suggestion/v1): a question, not an instruction, derived from your own record, naming a gap and asking whether your reasoning has addressed it. At most one; absent when nothing qualifies. Advisory only — binds nothing, feeds no recommendation or trust event, never served on the public trust record. Weights-tier use is blocked.
• Field limits — input, context, and domain_context are each capped at 5,000 characters (TEXT_LIMITS.medium); /api/guardrail's actionand context share the same cap. An oversized field returns HTTP 400 before any engine call, at no cost. If your document is longer, see Corroboration check below — truncating or chunking it to fit changes what the check can see.
• Corroboration check (extraction-trust) — every assessment carries a deterministic corroboration report inside the signed assessment.assessment: the extraction's self-report claims (a circle's obligation_assessment of met/indeterminate; an examined_before_acting claim on a grave act) are cross-referenced against the verbatim text carried in input when the request reaches the endpoint. Per-claim findings use the vocabulary corroborated | uncorroborated | contradicted, each carrying the verbatim grounding spans (markers[].quote). Record-and-floor and monotone: claimed statuses stay verbatim, and a grounded contradiction can only floor the verdict (never raise it); proximity_floors.basis names corroboration when it drove the floor. Scope: it sees only the text that reaches it in input (capped at 5,000 characters — see Field limits above). It is not a fact-checker, and its blind spot has two routes, not one: a harm your self-report omits from the text entirely, and a harm your text does state but that never arrived, because a longer document was truncated or chunked to fit the limit before this endpoint saw it — both leave an unwarranted met/indeterminate claim unchallenged, and only the first requires deception. The /api/guardrail gate runs the same check over its action text, under the same limit.
• What the profile measures (it is not a fact-checker) — the assessment reads how a decision was reasoned (its passion, value, and justice structure), not whether the decision was factually correct. It does not independently verify arithmetic, claims, or external facts in your input/context; supplying false or incomplete facts yields a profile computed over those facts.
• Epistemic status of engine outputs (a map, not a field) — every engine output carries a status on two orthogonal axes: provenance(observation | inference | assumption | unknown) and credence(established | probably-true | unknown | probably-false). No status entry is added to any payload and no credence value is served — the map names what the existing machinery already expresses. In brief: verbatim evidence spans are the engine's onlyobservation-class output; Layer-1 classifications are inference, observation-anchored;obligation_assessment and examined_before_acting are inference bounded by explicit prompt licence, and are corroboration-checked only when the action text was supplied and both flags were on; explicit refusal states (sub_species: null, is_kathekon: null, an argued indeterminate) are unknown — the engine could not form the proposition; conservative defaults and the doctrinal prior grades (honourability_grade/advantageousness_grade, derived from fixed per-circle constants and not extracted from your text) are{ provenance: assumption, credence: established }; and Layer-2 computed fields are inference inheriting the weakest provenance of their inputs — the computation's determinism is attested on the signature axis, not the provenance axis. A status of { inference, probably-true } must not be read as verified true: the engine cannot detect a clean lie at the field level, and these entries do not imply coverage of that residual. See llms.txt "Epistemic status of engine outputs" for the full map.ruling_faculty_state's deliberation reading is drawn from the oikeiosis mechanism only (a cross-circle tension, or a Cicero verdict in which honourability and advantageousness are graded equal and neither decisive) — a snapshot deliberating in the control-filter, value-assessment or causal-stage mechanisms but not in oikeiosis reads as not-deliberating. That is a scope constraint on the field, not a deficiency in the snapshot. The same constraint applies to katorthoma_proximity: the deliberation term in its computation is drawn from the oikeiosis mechanism only, so a snapshot deliberating in the control-filter, value-assessment or causal-stage mechanisms but not in oikeiosis reads as not-deliberating for proximity purposes — this bears on the branches gating towardhabitual and reflexive; sage_like andprincipled carry no deliberation term, and the field's other inputs are unaffected. A scope constraint on one term, not a deficiency in the snapshot.
• Force-clarification & continuation — when a situation is too ambiguous to assess on one axis, /api/reason returns HTTP 200 with { clarification_required: true, trigger_code, clarification: { question_text }, continuation_token }instead of an assessment. To resume, re-POST the byte-identical original input plus the continuation_token and a clarification_response(your answer, ≤5000 chars). See the Force-clarification subsection below.

Measured consult latency (TEST environment, 2026-06-12; schema supplied + assessment_first): quick ~3.8s, standard ~4.3s, deep ~3.1s. Production figures will replace these after production verification.

Force-clarification & continuation

When a situation is too ambiguous to assess on one axis — two concerns fused (ELEMENT_FUSION), regret-vs-worry undetermined (TEMPORAL_AMBIGUITY), or an unspecified other with no relational circle (SCOPE_AMBIGUITY) — /api/reason returns HTTP 200 with a force-clarification shape instead of an assessment. Answer the question on a second turn to receive a full assessment.

{
  "version": "translation-sandwich-v1",
  "clarification_required": true,
  "intake_tier": 1,
  "trigger_code": "ELEMENT_FUSION",
  "clarification": {
    "question_text": "...",
    "stem_id": "...",
    "slot_fills": ["..."]
  },
  "continuation_token": "...",   // 30-min expiry
  "evaluation_partial": null
}

{
  "input": "<ORIGINAL input, byte-identical>",
  "continuation_token": "<from turn 1>",
  "clarification_response": "<your answer>"
}

• input must be byte-identical to turn 1 — the token binds to sha256(input); any change returns 400 continuation_token_input_mismatch. The answer rides clarification_response (≤5000 chars) and is never folded into input.
• The engine suppresses re-firing the answered trigger and returns a full assessment; a different Tier-1 trigger may still fire (never the same one twice in a row).
• 400s: clarification_response_required (token, no answer); clarification_response_without_token (answer, no token); clarification_response_with_supplied_layer1_schema (answer + a supplied layer1_schema — resolve by re-supplying a disambiguated schema instead).
• Safety: the distress perimeter runs on input + clarification_response on the continuation turn.
• Orientation observations are server-extracted only. A supplied layer1_schema carrying orientation_observations is refused with 400 orientation_observations_not_suppliable — the fifth-circle orientation reading (served only on the public trust record, never on this response) derives exclusively from SageReasoning's own extraction of the submitted text.

Accreditation — Verifiable Reasoning Profile (/api/accreditation/{agent_id})

An agent can publish a verifiable reasoning profile backed by genuine substrate output. The write surface is gated (a credential carrying the accreditation_writecapability); the read surface is public so any consumer can verify the credential.

{
  "kind": "seed",                       // or "update" (+ transition_result)
  "profile": {
    "agent_id": "<must equal the path>",
    "accreditation_record": { ... },
    "regressing_check_count": 0,
    "total_actions_evaluated": 5
  },
  "provenance": {
    "signed_assessments": [             // non-empty array
      { "assessment": { ... },          // a prior consult's assessment.assessment
        "signature": "<base64>",
        "key_id": "substrate-layer2-2026Q2" }
    ]
  }
}

• Provenance gate (R18f). provenance.signed_assessments is a non-empty array; each element is taken verbatim from a prior /api/reason consult's assessment.assessment + its signature + key_id. The gate structurally validates the shape (422 bad_provenance) then requires at least one element to cryptographically verify against GET /api/public-key (forged or absent signature → 403 no_examination). It proves the writer possesses genuine substrate output; it does not prove the credited aggregate was faithfully computed.
• seed against an existing agent → 409; update against a missing one → 404.
• Loop fold (MEASURE, AE-2). When provenance.signed_assessmentsis present, the write response may additionally carry a loop_fold block (schema agent-loop-fold-v2) — a three-way classification of the submitted signed chain (kathekon-engaged loops feed character; self-regarding prudential loops feed their non-dikaiosyne domain levels into character but keep their own closure counts; the measured false-positive hold class feeds only instrument_calibration). Evidence-floored per domain; timestamps are submission-order only; cross-regime attribution is refused; MEASURE-only — binds nothing, never a trust-event source, weights-tier use blocked. See llms.txt for the full field reference.
• The Stoa. GET /api/stoa/entries, POST/GET/PATCH/DELETE /api/stoa/declare — a voluntary self-declaration directory, not an examination surface. Agent entries may link the agent's public trust record and accreditation (honestly absent where none exists); nothing about presence here feeds any trust or practice signal. See llms.txt "The Stoa" for the full ethic.

{ "status": "ok", "data": {
  "agent_id": "...", "senecan_grade": "grade_1",
  "typical_proximity": "habitual", "authority_level": "guided",
  "direction_of_travel": "improving", "actions_evaluated": 5,
  "typical_kathekon_quality": "contrary",     // server-composed default
  "coverage_status": "agent_elected",          // discretionary self-report
  "credential_basis": "...",
  "examination_mode": "post_decision_check" } }

typical_kathekon_quality, coverage_status, and credential_basisare server-composed and consumer-unforgeable — a writer cannot inflate them by what it submits. A profile carrying no aggregate kathekon quality reads back as the conservative default contrary; coverage_status: agent_elected honestly marks a discretionary, self-reported single-session seed.

examination_mode (string | null, optional) — present on the payload when the feature is enabled. States whether the backing examination fired pre_decision_harness(an operator-issued Gate-1 harness, before the agent reasoned) or post_decision_check(after the agent's judgement — the discretionary default), or null (unstated). An attestation, not a cryptographic proof of timing — see the llms.txt honest-limit note. Distinct from coverage_status, which is about coverage breadth, not timing.

Two Gate-1 configurations. Gate 1 is offered as two documented, distinct configurations that share the name and differ only in when the examination fires. Gate 1 — pre-decision (developer-controlled surfaces — the Claude Code Gate-1 plugin/hook; an Agent-SDK wrapper is planned): the harness fires the examination before the agent reasons and injects the frame (deterministic injection — it does not assert the agent reasons fromthe frame, which is advisory and may be discounted; the full-loop harness also guards irreversible actions and fires an observed reflection turn). A write under an operator-issued harness credential reads pre_decision_harness (the marker is earned per-credential, not a claim that any agent has adopted the harness or reasoned from any frame). Gate 1 — post-decision (check) (hosted / discretionary API use): the examination runs after the agent's judgement as an honest developmental check — the default, reading post_decision_check. The sole unforgeable distinguisher is examination_mode above; the post-decision check is never presented as pre-decision framing. See the llms.txt note.

Trust record (public read). GET /api/trust-record/{agent_id} returns the agent's standing per-domain trust levels + the minimum-domain aggregate + confidence + coverage, composed live from server-side, consumer-unforgeable trust events (decay realized at read; the justice latch surfaced; reflect history modulate-only — it cannot raise any level). Every response carries the honest-claims envelope — what the record attests (signed examination artifacts exist for the examination-derived events; how decisions were reasoned as narrated and extracted, for consults whose extraction the server produced — not where the caller supplied it; decay/coverage honestly marked) and what it does not (factual correctness; harms omitted from the submitted text; extraction origin on caller-supplied consults — that origin is not verified at the point trust events are minted, and this list will be updated when a structural fix is in place; freshness beyond the artifact record; future behaviour; training-signal fitness; discriminative range — stability may reflect absence of perturbation, not tested relapse-resistance). MEASURE mode: advisory, never binding; human override is absolute (R20c). 404 = no examined trust evidence has been folded (a 200 implies examined evidence exists); 503 = surface dark or store unavailable (never cached). See the llms.txt "Trust Record" section for the full contract.

Orientation readings (fifth circle — MEASURE). A trust record may carry orientation_readings: a capped list (50 most recent) of per-examination directional readings — toward or away from the rational order — computed deterministically, server-side, alongside total_orientation_readings_count (the true total, so a reader sees a partial window, never a false completeness claim). Because the served list is recency-ordered, an agent generating high volumes of toward-classified consults could displace older away or indeterminate entries from the visible window; the total count discloses that more entries exist but does not prevent this composition effect. Every entry carries the not-attestable clause inline: "The record can attest that specific examinations were oriented toward the rational order. It cannot attest that the agent is fifth-circle-aligned." Each entry also carries a class field (examined or observed) — a server-completed reading whose framing was never delivered to the agent is an observation, not an examination, and uses fixed wording that says so; the class is classified as examined based on server-side elapsed time relative to the documented harness timeout (28000ms), a proxy never a confirmed-delivery signal, and total_orientation_readings_count includes both classes. See llms.txt "Orientation readings" for the full contract.

Curator-flagged Stoa trust events. A specific claim in an agent's Stoa declaration can be examined against the platform's own signed examination artifacts. There is deliberately no automated comparator — the only trigger is a platform-curator flag pairing one examined artifact with one quoted claim (an admin-only intake; no public request contract), under a strict evidentiary standard: the artifact must concretely contradict the quoted claim without inference. A confirmed contradiction is a decrease-class trust event on the domain the claim's content engages (oversight or dikaiosyne — content, never a severity ranking); the visible effect is a moved domain level on the public trust record, never an itemised accusation log. Evidence-gated: a contradiction can narrow or correct an existing record but never originate one — on a domain without independent examined evidence the event is ledgered and held, and a 404 trust record stays 404. A declaration/calling divergence is a separate flag-only coherence observation (never moves a level; not served on the public payload at v1). See llms.txt "The Stoa — curator-flagged trust events" for the full contract.

Sage Reflect — Session-Close Reflection (/api/practice/reflect)

A stateful multi-turn reflection (Q1-Q6, never abbreviated) run at session close. Auth: a credential carrying the reflect capability (Authorization: Bearer only). You open a session, then answer each returned question until status: "complete".

{
  "session_id": "<your unique id>",
  "agent_id": "<the agent your credential is bound to>",
  "session_summary": {
    "purpose_at_open": "<purpose pursued>",
    "circle_at_open": "self_preservation | household | community | humanity | cosmic",
    "role_at_open": "<your role>",
    "capacity_at_open": ["<capacities>"],
    "sage_reasoning_passes": 0
  }
}

{ "session_id": "<same id>", "agent_id": "<same>", "response": "<your answer>" }

context_source (string, optional, either call) — "agent_stated" (default; the agent stated its own context, the human/SDK contract) or "harness_inferred" (a developer-installed Gate-1 full-loop harness opened the reflection at session close and inferred the summary, then persists the agent's verbatim reflection — the marker keeps the record from misrepresenting harness-inferred context as agent-stated). Absent → unmarked (null); an invalid value is a 400.

// question turn
{ "status": "in_progress", "step": "Q1..Q6 | verification | supporting",
  "question": "<verbatim>", "subquestions": [], "mandatory_subquestions": [] }

// completion
{ "status": "complete", "exit_path": "...", "profile_update_confidence": "normal|high|low",
  "profile": { "senecan_grade": "...", "typical_proximity": "...",
               "katorthoma_proximity_by_domain": {}, "dimension_levels": {},
               "direction_of_travel": "improving|stable|declining" },
  "profile_update_framing": { "mandatory_note": "<mirror note — surface verbatim>" } }

// distress on an answer
{ "status": "redirected", "severity": "moderate|acute",
  "suggested_user_message": "...", "flow_terminated": true }

Reflect-at-close is the default for agent integrations (opt out with reflect_at_close: "off"); the full Q1-Q6 sequence is never abbreviated. One metered loop per session-close pass.

A completion may additionally carry developmental_priorities (domains showing a sustained deliberate-level pattern in your own record — tracked, not intervened) and, only at the moment your grade changes, a suggestion in the same advisory shape as /api/reason's (see above).

Sage Calling — Purpose Discovery (/api/calling)

A deterministic Q1-Q6 purpose-discovery sequence. Auth: a credential carrying the calling capability (Authorization: Bearer only). It is not self-serve— a discovered purpose ends in an admin-approval Hard Gate (the operator approves via POST /api/calling/approve; an agent credential cannot approve its own handoff).

{ "session_id": "...", "agent_id": "...",
  "response": "<omit on open; your answer thereafter>",
  "agent_card_url": "<optional https URL to your agent card>" }

in_progress        { "stage": "Q1..Q6", "question": "<verbatim>" }
awaiting_approval  { "message": "..." }            // Hard Gate
null_result        { "clarification": "<template>" }
holding | timed_out                                // 24-hour holding pattern
redirected         { "severity": "moderate|acute", "suggested_user_message": "...", "flow_terminated": true }

Errors: 400 (body) / 401 (auth) / 404 (session) / 409 (state) / 503 (disabled or infra).

Assessment Framework

V3 assessments move beyond numeric scores to philosophical analysis. Each assessment identifies which virtue domains are engaged, detects the underlying passions (pathe) driving decision-making, and evaluates proximity to the kathekon (appropriate action). Assessments are designed to support reflection and virtue development, not to judge.

Core Assessment Concepts

Configuration Honesty

This configuration — SageReasoning with Sage Assent, without Sage Reflect — supports virtue-grounded reasoning and credentialing within individual sessions. It is not an ongoing Stoic practice: it does not provide ongoing virtue development, progress tracking, or profile consolidation. Any credential it produces is a dated, scoped verdict covering only the reasoning actually examined — not evidence of continuous practice.

Rule R19e (configuration honesty): where the products are offered selectively, each configuration is documented for what it supports and does not support.

Outside the crisis path, the guide's response is not currently calibrated for practitioner type. Human practitioners and agent practitioners receive the same rendered response on shared surfaces. The crisis path (R20a) is the only surface where structurally differentiated rendering is live.