Runtime API

Runs on your machines, default port 7466. It is part of the open-source runtime, so every route here is in a repository you can read.

Authentication is an agent token in Authorization: Bearer, or an opt-in mTLS client certificate whose subject CN is the agent name. Management routes use an API key carrying a role: viewer, approver or admin.

bash

curl -X POST http://127.0.0.1:7466/v1/actions/check \
  -H "Authorization: Bearer $MEMNOX_AGENT_TOKEN" \
  -H "content-type: application/json" \
  -d '{"action":"deploy.service","environment":"production"}'

Deciding

POST/v1/actions/checkagent

The full verdict. Creates an approval when one is needed, and appends exactly one audit event.

POST/v1/decisionagent

The same verdict, to inspect.

POST/v1/authorizeagent

200 or 403. For callers that want a yes or no and nothing else.

POST/v1/contextagent

What governs this, before doing it. Records nothing, raises no approval.

POST/v1/evaluate-riskagent

What the verdict would be. Audits nothing, creates no approval, asking is not attempting.

POST/v1/actions/outcomeagent

What actually happened after an allowed action.

POST /v1/actions/check

Body

actionstringrequired

The action verb, file.write, deploy.service, database.drop, mcp.*.

targetstring

The path, resource or service being acted on.

environmentstring

production, staging, or whatever you declared.

sessionIdstring

One agent run. Taint attaches here, so keep it stable across the whole run.

taintTaintSource[]

Where this session's context came from. Each entry carries a sourceType and, where the source has one, an actor.

approvalIdstring

Optional. The grant is claimed by fingerprint without it, which is what lets an editor hook close the loop.

json

{
  "action": "code.modify",
  "target": "src/payment/checkout.ts",
  "environment": "production",
  "sessionId": "run_8812",
  "taint": [{ "sourceType": "github_issue_comment", "actor": "NONE" }]
}

Response

effect'allow' | 'block' | 'require_approval' | 'redact'required

The verdict. Most restrictive matching policy wins.

reasonstring

Quoted from the rule that decided it. This is what a human reads when blocked.

approvalIdstring

Present when effect is require_approval. Poll it, then retry the action.

riskLevel'low' | 'medium' | 'high' | 'critical'

Classified deterministically from the verb and the environment.

matchedPoliciesstring[]

Every rule that matched, by name.

policyVersionstring

Content hash of the rule set in force. Recorded on the audit event too.

signalsstring[]

Which advisors escalated, and why.

json

{
  "effect": "require_approval",
  "approvalId": "a_7f31c2",
  "riskLevel": "high",
  "reason": "Money-handling code changes go through security review.",
  "matchedPolicies": ["payment-code-approval"],
  "policyVersion": "e852ac2d63d0",
  "signals": ["tainted-session"]
}

POST /v1/actions/outcome

json

{ "actionId": "…", "status": "succeeded", "detail": "3 files changed, tests green" }

status is succeeded, precondition_failed, execution_failed or postcondition_failed. A failed rollback audits as critical and opens an incident. See Verified execution.

Policies

GET/v1/policiesviewer

The rule set in force, with its version.

POST/v1/policies/validateadmin

Check a candidate rule set is well formed. Returns the full error list, not the first failure.

POST/v1/policies/reloadadmin

Re-read the policy files from disk.

Approvals

GET/v1/approvals/:idagent · admin

Poll one approval. The only route an agent token may read beyond the decision endpoints, it 403s on anyone else's.

POST/v1/approvals/:id/approveapprover

Grant it. Grants accumulate toward minApprovals; one person counts once.

POST/v1/approvals/:id/denyapprover

Refuse it. A single denial ends the request, whatever the quorum.

POST/v1/approvals/:id/overrideadmin

Break-glass. Reason mandatory, audited as critical, refused with 403 for the non-overridable class.

Agents

GET/v1/agents/:idviewer

One agent's identity, capabilities and deterministic trust score.

POST/v1/agents/:id/rotateadmin

Issue a new credential. The old one is retired on return.

Memory

POST/v1/memory/searchviewer

Search recorded decisions. Keyword by default, hybrid when an embedding key is configured.

POST/v1/memory/decisionsadmin

Record a decision with its provenance. This is what the control plane writes to when a human approves a suggestion.

Audit and operations

GET/v1/auditviewer

Decisions, newest first. ?org=acme filters by tenant.

GET/v1/audit/verifyviewer

Chain verification as JSON, the same answer memnox audit verify prints.

GET/v1/metrics

Prometheus text. Counters are per process; summing across pods is the scrape layer's job.

GET/healthznone

Liveness. Unauthenticated on purpose, so a load balancer can reach it.

Failure behaviour

This table is the contract, and it is deliberately unforgiving.

Situation

Unknown token

Blocked, audited as critical

Suspended agent

Blocked

Action outside declared capabilities

Blocked, before policy runs

Taint store unreadable

Session treated as tainted

An advisor cannot run

Raises nothing, a broken advisor never blocks

Rate limit exceeded

Blocked, and counted in metrics

SDKs

Clients that wrap all of this, in three languages.

Contributing to the runtime

How to add a route, an advisor or a policy pack.