CGR API Reference

The CGR endpoints let you record governed judgment decisions, their resolved outcomes, and peer reviews, and read the resulting per-(agent, domain) reputation. See CGR concepts for the model.

Availability

Live in GRAFOMEM Cloud (early). Endpoints and scoring work today; the reputation layer is young — don't assume production-scale throughput.

Authentication

All CGR endpoints are tenant-scoped. Authenticate with your tenant API key in the X-API-Key header:

curl -H "X-API-Key: <your-tenant-api-key>" \
  https://cloud.grafomem.com/v1/cgr/scores

Reading reputation requires the cgr:read scope; recording decisions, outcomes, and reviews requires a valid tenant context.

How this differs from Decision Trail and the Governance Gateway

These three surfaces are easy to conflate. They answer different questions:

Surface	Prefix	Question it answers	When
Governance Gateway	/v1/governance	"Is this operation allowed to run?" — rate limits, model allowlists, content/PII filters, HITL gates	before execution
Decision Trail	/v1/decisions	"What happened?" — immutable, Ed25519-signed audit log of every inference	at execution
CGR	/v1/governed/* + /v1/cgr/scores	"How well-calibrated has this agent proven to be?" — reputation from resolved outcomes	after outcomes resolve

Note the naming: /v1/governed/decisions (CGR substrate — a judgment decision that can later earn reputation) is not the same as /v1/decisions (the general inference audit log).

Record a governed decision

POST /v1/governed/decisions — record a governed judgment decision. Only decisions tagged as judgment can earn reputation; deterministic/rule outputs are recorded but earn nothing.

curl -X POST https://cloud.grafomem.com/v1/governed/decisions \
  -H "X-API-Key: <your-tenant-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "certify",
    "reason": "supporting documents consistent",
    "invoice_id": "REF-1001",
    "context": { "amount": 4200 },
    "model_id": "your-model-v1",
    "agent_handle": "certifier@your-domain",
    "verifiability_tag": "judgment",
    "agent_key": "<agent-ed25519-public-key-hex>"
  }'

Field	Type	Notes
decision	string	certify or reject
reason	string	free-text rationale
invoice_id	string?	the referent this decision is about
context	object	the fields the decision was made on
model_id	string	model identifier
agent_handle	string	the deciding agent
verifiability_tag	string	judgment (scored) or rule (earns nothing)
agent_key	string?	the acting agent's Ed25519 public key (hex), supplied by the emitter. Absent ⇒ the decision is unbindable and stays unproven.

Record an outcome

POST /v1/governed/outcomes — record how a decision's referent actually resolved. This is the verifiable channel: resolved outcomes update the Beta posterior directly.

curl -X POST https://cloud.grafomem.com/v1/governed/outcomes \
  -H "X-API-Key: <your-tenant-api-key>" \
  -H "Content-Type: application/json" \
  -d '{ "invoice_ref": "REF-1001", "outcome": "paid", "source": "manual" }'

Field	Type	Notes
invoice_ref	string	joins the outcome to the decision's referent
outcome	string	e.g. paid, default, disputed, late, written_off
outcome_date	string?	ISO-8601; defaults to now
amount_recovered	number?	optional
source	string	provenance of the outcome (e.g. manual)

Bulk: POST /v1/governed/outcomes/bulk accepts a JSON array of the same objects.

Record a review

POST /v1/governed/reviews — record a peer review of a decision. This is the review channel: each review's contribution is scaled by the reviewer's calibration weight (see the review gate).

curl -X POST https://cloud.grafomem.com/v1/governed/reviews \
  -H "X-API-Key: <your-tenant-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice_ref": "REF-1001",
    "reviewer_handle": "reviewer@your-domain",
    "rating": 0.9,
    "agent_handle": "certifier@your-domain",
    "source": "analyst"
  }'

Field	Type	Notes
invoice_ref	string	referent under review
reviewer_handle	string	the reviewer (dedup key with invoice_ref)
rating	number	in [0, 1]
agent_handle	string?	who certified; back-filled at score time if omitted
decision_id	string?	precise referent
review_date	string?	ISO-8601; defaults to now
source	string	e.g. analyst, manual

Bulk: POST /v1/governed/reviews/bulk accepts a JSON array. Within one batch, duplicates by (invoice_ref, reviewer_handle) collapse to the last entry.

Read reputation

GET /v1/cgr/scores — the current reputation for every scored agent in your tenant. Requires cgr:read.

curl -H "X-API-Key: <your-tenant-api-key>" \
  "https://cloud.grafomem.com/v1/cgr/scores?limit=500"

{
  "scores": [
    {
      "agent_handle": "certifier@your-domain",
      "cgr_score": 0.82,
      "confidence": 24.0,
      "n_resolved": 22,
      "n_pending": 3,
      "capability_tier": null,
      "as_of": "2026-08-18T00:00:00Z",
      "dimension": "receivables"
    }
  ],
  "count": 1,
  "as_of": "2026-08-18T00:00:00Z",
  "dimension": "receivables"
}

Field	Meaning
cgr_score	posterior mean α / (α + β)
confidence	evidence mass n = α + β — n_resolved plus the neutral prior's two pseudo-counts (e.g. 22 resolved ⇒ 24)
n_resolved	resolved judgment-certifies that updated the posterior
n_pending	judgment-certifies still awaiting an outcome
capability_tier	reserved; not currently assigned (null)
dimension	the reputation domain (currently receivables)

Score and confidence travel together — a score is only as trustworthy as the evidence mass behind it.

GET /v1/cgr/scores/{agent_handle} returns a single agent's score object (404 if that agent has no score yet).