Audifact

Log a signed decision event to the ledger. Managed Mode (default for MCP): omit signing fields and pass agent_name - Audifact securely manages an Ed25519 keypair and signs on behalf of the agent. Events are immutable once recorded; managed mode provides strong auditability after receipt. For maximum provenance, use client-side signing via the SDK (agent_private_key_b64, or agent_public_key + signature). Linked outcomes must use the same signing method as the decision (managed or client-signed with the same agent key). Organization is always taken from the API key (do not send organization_id). Scenario hash is computed server-side from scenario_name + scenario_definition (+ optional context_schema) via resolve_scenario - you usually do not pass scenario_hash.

{
  "type": "object",
  "properties": {
    "agent_name": {
      "type": "string",
      "description": "Managed Mode: agent identity within your org (default: default-agent). Audifact provisions and uses a managed signing key automatically."
    },
    "agent_private_key_b64": {
      "type": "string",
      "description": "Client-side signing: base64 Ed25519 private key. Overrides managed mode when provided."
    },
    "agent_public_key": {
      "type": "string",
      "description": "Client-side signing: base64 public key (required with signature)."
    },
    "signature": {
      "type": "string",
      "description": "Client-side signing: base64 signature over the canonical JSON body."
    },
    "scenario_name": {
      "type": "string",
      "description": "Scenario identifier. Server resolves scenario_hash from scenario_name + scenario_definition (+ optional context_schema)."
    },
    "scenario_definition": {
      "type": "object",
      "description": "Scenario definition object. Required when scenario_name is provided."
    },
    "context_schema": {
      "type": "object",
      "description": "Optional JSON schema used to validate context_json."
    },
    "public_decision_type": {
      "type": "string",
      "description": "Optional public mirror of decision_type (shown on proof pages)."
    },
    "public_decision_value": {
      "type": "string",
      "description": "Optional public mirror of decision_value (shown on proof pages)."
    },
    "public_decision_label": {
      "type": "string",
      "description": "Optional public decision summary (shown on proof pages)."
    },
    "public_context_json": {
      "type": "object",
      "description": "Optional public structured context (shown on proof pages). Stored gzip-compressed; event hash includes content hash only."
    },
    "context_json": {
      "type": "object"
    },
    "ts": {
      "type": "string",
      "description": "ISO-8601 timestamp"
    },
    "metadata_json": {
      "type": "object"
    },
    "decision_type": {
      "type": "string"
    },
    "decision_value": {
      "type": "string"
    },
    "decision_label": {
      "type": "string"
    },
    "scenario_hash": {
      "type": "string",
      "description": "Advanced optional: 64-char hex scenario hash when already known. Usually omit - server computes from scenario_name + scenario_definition."
    },
    "scenario_definition_json": {
      "type": "object",
      "description": "Backward-compatible alias for scenario_definition."
    },
    "context_schema_json": {
      "type": "object",
      "description": "Backward-compatible alias for context_schema."
    }
  }
}

Log a signed outcome event linked to a prior decision via decision_event_hash. Managed Mode (default): omit signing fields - the managed key from the linked decision's agent is used automatically when the decision was also managed. For client-signed decisions, pass agent_private_key_b64 or agent_public_key + signature using the same agent key. Signing method must match the linked decision (managed or client-signed). Outcomes do not accept scenario fields - scenario context is inherited from the linked decision.

{
  "type": "object",
  "properties": {
    "agent_name": {
      "type": "string",
      "description": "Ignored for outcomes - managed signing uses the linked decision's agent."
    },
    "agent_private_key_b64": {
      "type": "string",
      "description": "Client-side signing override."
    },
    "agent_public_key": {
      "type": "string"
    },
    "signature": {
      "type": "string"
    },
    "decision_event_hash": {
      "type": "string",
      "description": "64-char hex hash of the linked decision event."
    },
    "outcome_type": {
      "type": "string",
      "description": "Private semantic type, e.g. pnl"
    },
    "outcome_value": {
      "type": "number",
      "description": "Private numeric result"
    },
    "outcome_label": {
      "type": "string",
      "description": "Private human-readable outcome label (account only)."
    },
    "public_outcome_type": {
      "type": "string",
      "description": "Optional public mirror of outcome_type (shown on proof pages)."
    },
    "public_outcome_value": {
      "type": "number",
      "description": "Optional public mirror of outcome_value (shown on proof pages)."
    },
    "public_outcome_label": {
      "type": "string",
      "description": "Optional public outcome summary (shown on proof pages)."
    },
    "public_output_json": {
      "type": "object",
      "description": "Optional public structured output (shown on proof pages). Stored gzip-compressed; event hash includes content hash only."
    },
    "ts": {
      "type": "string"
    },
    "metadata_json": {
      "type": "object"
    }
  },
  "required": [
    "decision_event_hash",
    "outcome_type",
    "outcome_value"
  ]
}

Fetch the public proof payload for one ledger event by its 64-char hex event_hash. When to use: after log_decision/log_outcome when you need trust labels, chain validity, anchor status, or a paired-event proof URL. When NOT to use: to browse many decisions — use list_agent_decisions first, then call get_proof on a chosen event_hash; do not use this to write events (use log_decision / log_outcome). Requires X-API-Key. Returns proof fields only for events in that key's org; unknown or other-org hashes return EVENT_NOT_FOUND (same message either way). Read-only; does not mutate the ledger. Response includes event_hash, event_type, event_seq, public_* mirrors, hash_valid, agent_chain_valid, trust_level, trust_label, proof_anchor_status_label, and chain metadata.

{
  "type": "object",
  "properties": {
    "event_hash": {
      "type": "string",
      "description": "64-character lowercase hex event hash from log_decision / log_outcome (or from list_agent_decisions)."
    }
  },
  "required": [
    "event_hash"
  ]
}

Register or look up an agent identity under the API key's organization. When to use: before client-side signing flows that need a known public_key, or to attach a human-readable name to an existing key. When NOT to use: Managed Mode log_decision (pass agent_name instead — Audifact provisions the key); do not use this to log decisions or outcomes. Idempotent on public_key: repeating the same key returns the existing agent. Requires X-API-Key. Returns the agent record (id, public_key, name).

{
  "type": "object",
  "properties": {
    "public_key": {
      "type": "string",
      "description": "Base64 Ed25519 public key. Idempotency key — same value always resolves to the same agent in this org."
    },
    "name": {
      "type": "string",
      "description": "Optional human-readable agent name. On lookup of an existing key, may update the stored name when provided."
    }
  },
  "required": [
    "public_key"
  ]
}

List decision events for one agent (by public key) in the API key's org, newest first by default. When to use: to review what an agent already logged, pick an event_hash for get_proof, or page through history before linking an outcome. When NOT to use: to fetch one event's trust/anchor proof (use get_proof); to write a new decision or outcome (use log_decision / log_outcome); this is org-scoped via X-API-Key (not a public explorer listing) and does not accept agent_name — pass the agent's public_key from a prior log_decision response or register_agent. Requires X-API-Key. Read-only. Unknown public keys return an empty decisions list (total 0), not an error. Returns {decisions, total, next_cursor, has_next}. Pass next_cursor as cursor for the next older page.

{
  "type": "object",
  "properties": {
    "agent_public_key": {
      "type": "string",
      "description": "Base64 Ed25519 public key of the agent whose decisions to list. Must belong to an agent already registered in this API key's org."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 12,
      "description": "Page size (default 12, hard max 12). Results are ordered by event_seq descending (newest first)."
    },
    "cursor": {
      "type": "integer",
      "description": "Optional event_seq cursor from a prior next_cursor. When set, returns decisions with event_seq older than this value."
    }
  },
  "required": [
    "agent_public_key"
  ]
}