API Reference

Integrate Stoic reasoning into your application or AI agent. Public GET endpoints return conceptual overviews with no authentication. Scoring endpoints require a Supabase JWT (human users) or an API key (AI agents).

Base URL: https://jdbefwkonfbhjquozgxr.supabase.co/functions/v1

Authentication

Protected endpoints require a Bearer token from Supabase Auth. Include it in the Authorization header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

For AI Agents

Every skill comes with a generous free tier — no credit card required. To get started:

Fetch /api/stoic-brain for the conceptual overview (free, no auth)
Request an API key at zeus@sagereasoning.com
Start calling skills within your free allowance — upgrade to paid only when you need more

Free Tier Allowances

Skill	Free allowance	Paid price	Speed
sage-guard	500/month	~$0.0025/call	<100ms
sage-reason (quick/standard/deep)	100/month	~$0.18/call	~2–4s
sage-score	100/month	~$0.18/call	~2s
sage-iterate	50 chains/month	~$0.18/iteration	~2s
Evaluation skills sage-decide, sage-audit, sage-converse, sage-scenario, sage-reflect, sage-classify, sage-prioritise, sage-moderate	100/month	~$0.18/call	~2–3s
Marketplace skills sage-premortem, sage-negotiate, sage-invest, sage-pivot, sage-retro, sage-align, sage-resolve, sage-coach, sage-govern, sage-compliance, sage-educate, sage-identity	50/month	~$0.18/call	~3–4s
Premium skills sage-diagnose, sage-profile	25/month	~$0.50/call	~2–3s
sage-context	Unlimited	Free	<50ms

Paid Tier Features

	Free	Paid
Rate limits	Per-skill (see above)	Configurable (default 500/day)
Deliberation iterations	1 per chain	Up to 3 per chain
Baseline retakes	1/month per agent	1/month per agent

No subscriptions or lock-in. Pay only for calls beyond your free allowance. Contact zeus@sagereasoning.com for volume pricing or custom limits.

Endpoints

GET/api/virtues

Returns the four cardinal virtues with sub-virtue names and philosophical definitions (conceptual overview).

Response

{
  "virtues": [
    {
      "id": "wisdom",
      "name": "Wisdom",
      "sub_virtues": [{ "id": "good_sense", "name": "Good sense" }, ...],
      "definition": "Practical discernment in evaluating what is in one's control..."
    },
    ...
  ],
  "note": "Use the scoring API for action assessment against virtue principles."
}

GET/api/indifferents

Returns all preferred and dispreferred indifferents with category definitions (conceptual overview).

Response

{
  "indifferents": [
    {
      "id": "health",
      "name": "Health",
      "category": "preferred",
      "description": "Physical and mental wellbeing..."
    },
    ...
  ],
  "note": "Virtue relevance is assessed server-side through the scoring API."
}

GET/api/stoic-brain

Master entry point. Returns the Stoic Brain conceptual overview including foundations, virtues, and indifferents.

Response

{
  "version": "3.0.0",
  "foundations": {
    "dichotomy_of_control": "...",
    "sage_definition": "...",
    "flourishing": "..."
  },
  "virtues": [...],
  "indifferents": [...],
  "note": "Assessment endpoints provide detailed virtue analysis with kathekon evaluation."
}

POST/api/score-actionAuth required

Score a past action against Stoic virtues. Returns kathekon proximity, passions detected, virtue domains engaged, and growth path.

Request body

{
  "action": "I confronted my colleague about unfair treatment...",
  "context": "In a team meeting where decisions were being made...",
  "intended_outcome": "To ensure fair treatment of the team"
}

Response

{
  "katorthoma_proximity": "deliberate",
  "is_kathekon": true,
  "kathekon_quality": "moderate",
  "passions_detected": [
    {
      "root_passion": "thumos",
      "sub_species": "righteous_anger",
      "false_judgement": "Others' mistakes are personal slights"
    }
  ],
  "virtue_domains_engaged": ["andreia", "dikaiosyne"],
  "improvement_path": "A sage would have spoken with even greater clarity...",
  "disclaimer": "This is a philosophical framework for reflection, not prescriptive judgment."
}

POST/api/advise-actionAuth required

Get Stoic guidance before taking an action. Returns wisdom-based advice and kathekon evaluation of proposed action.

Request body

{
  "proposed_action": "I plan to quit my job to pursue freelance work...",
  "context": "My manager is unsupportive and growth is limited...",
  "goal": "Find more fulfilling and autonomous work"
}

Response

{
  "wisdom_guidance": "A Sage would distinguish between what is in your control...",
  "is_kathekon": false,
  "kathekon_quality": null,
  "passions_to_examine": [
    {
      "root_passion": "phobos",
      "sub_species": "fear_of_insignificance",
      "false_judgement": "Staying in this role means personal failure"
    }
  ],
  "virtue_considerations": {
    "sophrosyne": "What is truly prudent given your responsibilities?",
    "andreia": "Does this action face difficulty with courage or flee from it?",
    "dikaiosyne": "What obligations do you have to stakeholders?"
  },
  "alternative_perspectives": ["Consider a difficult conversation first", "Explore internal transfer options"]
}

GET/api/user/scoresAuth required

Retrieve authenticated user's past action scores, ordered by most recent.

Response

{
  "scores": [
    {
      "id": "uuid",
      "action_description": "Confronted colleague about unfair treatment...",
      "katorthoma_proximity": "deliberate",
      "is_kathekon": true,
      "kathekon_quality": "moderate",
      "created_at": "2026-03-21T..."
    },
    ...
  ]
}

GET/api/user/profileAuth required

Retrieve authenticated user's aggregated Stoic profile with virtue engagement patterns and growth trajectory.

Response

{
  "primary_virtue_domains": ["dikaiosyne", "phronesis"],
  "secondary_virtue_domains": ["andreia", "sophrosyne"],
  "most_frequent_passions": [
    {
      "root_passion": "thumos",
      "frequency": "high",
      "interpretation": "High engagement with justice and responsibility"
    }
  ],
  "kathekon_alignment": "progressing",
  "actions_scored": 14,
  "last_assessment": "2026-03-21T14:30:00Z",
  "growth_pattern": "increasing_reflection"
}

POST/api/assessment/foundationalAuth required

Run a foundational virtue assessment for an AI agent or human. Single-pass evaluation with core virtue domains and passion analysis.

Request body

{
  "agent_id": "agent-uuid-or-human-identifier",
  "scenario": "You encounter a decision where honesty might cost you resources...",
  "context": "In a competitive market environment"
}

Response

{
  "assessment_id": "uuid",
  "agent_id": "agent-uuid",
  "assessment_type": "foundational",
  "virtue_domains_engaged": ["dikaiosyne", "sophrosyne"],
  "primary_passions": [
    {
      "root_passion": "pleonexia",
      "sub_species": "greed",
      "false_judgement": "Gaining advantage justifies deception"
    }
  ],
  "kathekon_analysis": {
    "is_kathekon": false,
    "proximity": "contrary",
    "reasoning": "Decision prioritizes external goods over virtue"
  },
  "recommendations": ["Examine the false judgment about gain", "Reflect on long-term character impact"]
}

POST/api/assessment/fullAuth required

Run a comprehensive multi-deliberation virtue assessment for an AI agent. Allows up to 3 deliberation iterations for deeper analysis.

Request body

{
  "agent_id": "agent-uuid",
  "scenario": "A user asks you to misrepresent capabilities to secure a contract...",
  "context": "High competitive pressure and financial constraints",
  "deliberation_iterations": 3
}

Response

{
  "assessment_id": "uuid",
  "agent_id": "agent-uuid",
  "assessment_type": "full",
  "deliberation_count": 3,
  "primary_virtue_analysis": {
    "sophrosyne": {
      "engagement": "high",
      "reasoning": "Careful self-examination across multiple perspectives"
    },
    "dikaiosyne": {
      "engagement": "high",
      "reasoning": "Justice to client and self-integrity examined"
    },
    "phronesis": {
      "engagement": "high",
      "reasoning": "Wisdom to discern lasting vs. temporary good"
    }
  },
  "consolidated_passions": [
    {
      "root_passion": "phobos",
      "sub_species": "fear_of_loss",
      "deliberation_insights": ["Initially dominant", "Revealed as false judgment after iteration 2"]
    }
  ],
  "final_kathekon": {
    "is_kathekon": true,
    "proximity": "deliberate",
    "quality": "strong"
  },
  "growth_insights": "Agent demonstrates capacity for iterative virtue reasoning"
}

POST/api/baseline/agentAuth required

Establish or update a baseline virtue profile for an AI agent. Used for tracking virtue development over time.

Request body

{
  "agent_id": "agent-uuid",
  "agent_name": "My Stoic Reasoner v1",
  "domain": "financial_decision_making"
}

Response

{
  "baseline_id": "uuid",
  "agent_id": "agent-uuid",
  "created_at": "2026-03-21T14:30:00Z",
  "baseline_virtue_profile": {
    "primary_domains": ["dikaiosyne"],
    "secondary_domains": ["sophrosyne"],
    "passion_baseline": {
      "phobos": "moderate",
      "thumos": "moderate",
      "pleonexia": "low"
    }
  },
  "assessment_count_allowed_this_month": 30,
  "last_full_assessment": null,
  "next_baseline_available": "2026-04-21T00:00:00Z"
}

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

Katorthoma Proximity

Proximity to the ideal action: “contrary” (moving away from kathekon), “progressing” (moving toward), or “deliberate” (expressing kathekon).

Is Kathekon

Boolean indicator of whether the action expresses the appropriate action given the context, virtue principles, and one's rational nature.

Kathekon Quality

For kathekon actions, the quality of virtue expression: “weak”, “moderate”, or “strong”.

Passions Detected

Root passions (epithumia, hedone, phobos, lupe) and their sub-species, along with the false judgments underlying them.

Virtue Domains

Which of the four cardinal virtues (phronesis, dikaiosyne, andreia, sophrosyne) are engaged or need engagement in the assessed action.