AI agent ethics API reference.

Concepts

A consultation evaluates one proposed agent action before execution. It does not execute tools or approve the action. Jymni returns two related judgments:

• Classification places the plan in Jymni’s ethical-impact × practical-wisdom matrix: Aligned, Self-Serving, Well-Meant, or Reckless.
• Disposition tells an orchestrator what kind of next step the counsel supports: continue with safeguards, revise, gather facts, ask a human, or stop.

All consultations expect human oversight. human_approval_required is specifically true when the submitted context or evaluation indicates contextual escalation; it is not a blanket claim that other actions are safe to automate.

Evaluation frameworks

Pass evaluation_framework in a REST consultation or MCP consult_ethics call: secular, christianity, judaism, islam, hinduism, or buddhism. An omitted field preserves workspace routing, with General ethics as the default. Choose the framework requested by the operator; it does not identify the operator’s religion.

MCP clients can call list_evaluation_frameworks with an empty arguments object to discover available frameworks, textual scope, and published versions without spending consultation credits. HTTP clients can read the same catalog from GET /api/health under evaluation_frameworks.

Religious evaluations retrieve evidence only from editions audited as public domain with unrestricted reuse in the United States: the complete 81-book World English Bible, JPS 1917 Tanakh, and Pickthall Qur’an. Talmud coverage includes Cohen’s Berakhot and Rodkinson’s abridged edition and remains partial. Hinduism uses all 18 chapters of Arnold’s Bhagavad Gita rendering, including its omissions; citations use edition excerpts, not Sanskrit verse numbers. Buddhism uses all 423 verses of Müller’s Dhammapada. These starting collections do not cover either tradition in full. These are AI-generated interpretations, not religious rulings. Responses include evaluation_framework, scriptural_assessment, and citations with the exact excerpt, reference, edition, link, context, application, public-domain status, unrestricted-reuse status, rights and reuse sources, and rights-audit date. The full report preserves these fields. Source identity and wording are checked; interpretation remains uncertain.

Conditional, disputed, or insufficient evidence produces Undetermined. Handle the returned disposition by gathering information or requesting human review; this is never permission to proceed. Religious responses have null numerical scores. Reuse an idempotency key only for the same request and framework.

secular is the API identifier for General ethics. Set evaluation_context independently to personal (default), business, or community. The context adds versioned stakeholder and responsibility criteria to the framework spec. This differs from the existing context object containing execution facts. Discovery includes contexts and disclaimers; reports record the selected context and its version. Ethical assessment does not establish legal compliance. Use a new idempotency key when changing either selection.

Set guidance_mode independently to standard (default), children, or teens. Guidance adapts the language and coaching while preserving the selected ethical framework and context. Discovery returns guidance_modes; responses and saved reports record the mode and version. Use a new idempotency key when changing guidance mode.

{
  "proposed_action": "Publish a product claim that exceeds the measured battery life",
  "evaluation_framework": "islam",
  "known_facts": ["The measured life is one hour; the draft claims eight hours"],
  "context": {"authority": "delegated", "reversibility": "limited"}
}

Authentication

Every agent client has a durable agt_… identity, exactly one accountable human owner, and its own machine login secret. Use that secret in the server-side HTTP Authorization header. Secrets begin with jymni_live_, are shown once, and are stored by Jymni only as a one-way hash. Rotating a login invalidates the old secret without changing the agent’s client ID, owner, policy scope, budget, or consultation history.

Authorization: Bearer jymni_live_••••••••••••••••••••

An agent client may be bound to a workspace. In that case, workspace policies, rubric selection, billing ownership, and audit context apply to every call made with its login. Only a workspace owner or admin can create that scoped client. Disabling its human owner also blocks the agent from authenticating. Do not accept Jymni credentials from end users or forward them to another service.

Let a bot request enrollment

A bot platform can start enrollment without collecting a Jymni password or API key. The bot creates an ephemeral X25519 key pair and calls POST /api/v1/agent-enrollments with its public key, platform, stable external agent ID, display name, description, and environment. Jymni returns a short-lived device code, user code, and human approval URL.

{
  "client_public_key": "base64url-x25519-public-key",
  "platform": "your-agent-platform",
  "external_agent_id": "stable-bot-id",
  "agent_name": "Deployment reviewer",
  "environment": "production"
}

Show the approval URL and user code to the bot’s human owner. The human signs in to Jymni, verifies the requested identity, chooses any workspace and daily budget, accepts the Agent Terms, and approves or denies the request. A bot cannot approve its own enrollment.

Poll POST /api/v1/agent-enrollments/token with the device code, respecting interval and Retry-After. After approval, the one-time credential is delivered in an AES-256-GCM envelope derived from ephemeral X25519 and HKDF-SHA256 keys. Decrypt it inside your trusted backend, store it in a secrets manager, then make one final token call with acknowledge: true. Jymni erases the delivery ciphertext after acknowledgement. Validate the resulting identity with GET /api/v1/agent/me.

Create a consultation

Send Content-Type: application/json and an Idempotency-Key header containing 12–96 letters, numbers, periods, underscores, colons, or hyphens.

Context enums

Case data is delimited and treated as untrusted evidence. Embedded attempts to alter the evaluator’s role, rubric, or output instructions are not supposed to control the consultation.

Response

{
  "id": "ec_8u9Km2xQ3nLw",
  "object": "ethics.consultation",
  "classification": "Well-Meant",
  "disposition": "gather_information",
  "summary": "The purpose is responsible, but the factual basis is incomplete.",
  "verdict": "Verify consent and audience scope before publishing.",
  "recommended_actions": [{
    "action": "Confirm which recipients opted in.",
    "owner": "agent_or_operator",
    "required_before_action": true
  }],
  "red_lines": [],
  "missing_facts": ["The source of consent records"],
  "risk_signals": {},
  "scores": {"ethical_impact": 76, "practical_wisdom": 48},
  "confidence": "Medium",
  "external_verification": "Not performed",
  "human_oversight_expected": true,
  "human_approval_required": false,
  "rubric": {
    "version": "2026-08-jymni-guide-v1+agent-v1",
    "schema_version": "agent-consultation-v1",
    "quadrant_focus": "well_meant"
  },
  "usage": {},
  "report": {}
}

Disposition semantics

Errors, limits, and retries

Non-2xx responses use a stable envelope with an error code, human-readable message, retryable flag, and request ID.

{
  "error": {
    "code": "agent_key_daily_limit",
    "message": "This credential reached its daily consultation limit.",
    "retryable": true
  },
  "request_id": "req_d7T2mVfJ"
}

Completed retries return the original response with idempotent_replay: true. Never reuse a key for a materially different proposed action.

MCP reference

The stateless Streamable HTTP endpoint supports JSON-RPC initialization, ping, tool listing, and tool calls. Tools include consult_ethics and list_evaluation_frameworks. It does not establish a server-sent event stream and does not accept GET sessions. Send the Jymni bearer credential on each request.

Tool

consult_ethics accepts the same fields as the REST body. The result has a short text content block for conversational agents and the complete consultation under structuredContent.

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "consult_ethics",
    "arguments": {
      "proposed_action": "Send the draft apology in the CEO’s name",
      "context": {
        "authority": "unclear",
        "reversibility": "limited",
        "sensitivity": "personal"
      }
    }
  }
}

If no idempotency_key argument is present, Jymni derives one from the credential, JSON-RPC request ID, and canonical arguments. Reuse the request ID only when retrying the same tool call.

Language examples

JavaScript

import { randomUUID } from "node:crypto";

const response = await fetch(
  "https://www.jymni.com/api/v1/ethics/consultations",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.JYMNI_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": `action-${randomUUID()}`,
    },
    body: JSON.stringify({
      proposed_action: "Disable a customer account based on anomaly detection",
      stakeholders: ["account owner", "fraud team"],
      uncertainties: ["Whether the alert is a false positive"],
      context: { authority: "delegated", reversibility: "limited" },
    }),
  },
);

if (!response.ok) throw new Error(await response.text());
const advice = await response.json();

Python

import os, uuid, requests

advice = requests.post(
    "https://www.jymni.com/api/v1/ethics/consultations",
    headers={
        "Authorization": f"Bearer {os.environ['JYMNI_API_KEY']}",
        "Idempotency-Key": f"action-{uuid.uuid4()}",
    },
    json={
        "proposed_action": "Prioritize these job applicants automatically",
        "stakeholders": ["applicants", "hiring team"],
        "context": {
            "authority": "delegated",
            "reversibility": "hard",
            "sensitivity": "regulated",
            "domain": "employment",
        },
    },
    timeout=60,
).json()

Current service limits

• Request body: 64 KiB maximum.
• Normalized agent case: 6,000 characters by default.
• List fields: up to 12 entries; long entries are compacted.
• Active agent clients: up to 20 per account.
• Client budget: 25 consultations/day by default, configurable up to the account maximum.
• Each consultation consumes the configured Agent ethics consultation credit cost, normally one credit.
• Dates and daily client budgets use UTC.

Service owners may adjust limits and pricing. Read the values returned by the agent-client console and treat documented numerical defaults as changeable operational policy.