API reference · Trust Fabric

Ask the control plane to decide on a proposed action

POST /fabric/decisions

Last reviewed 2026-11-06

POST /fabric/decisions

Request body

DecisionRequest (required)

Field	Type	Meaning
`service`	string or null	catalog slug this call targets
`path`	string or null	upstream path this call targets
`payload`	object	the request body the agent intends to send
`plan`	array of object	ordered [{tool, args}] plan for ActionProof
`agent_id`	string or null	max length `255`
`provenance`	object or null	where each payload argument came from, keyed by dotted path: user \| system \| tool:<name> \| memory:<id> \| web:<url> \| file:<ref> \| agent:<id> \| untrusted. An untrusted value in a recipient, URL, predicate, role, amount, account, command or SQL argument is denied; an unreadable label is denied.
`chain_id`	string or null	your run id: every decision sharing it forms one trace pattern `^[A-Za-z0-9._:-]{1,128}$`
`record`	boolean	set false to evaluate without writing an evidence record default `true`
`scitt_notarize`	boolean or null	set true to anchor and notarize this decision in SCITT Merkle tree

Responses

Status	Meaning	Body
`200`	The decision. Run the tool only when verdict starts with ALLOWED.	`Decision`
`401`	The X-API-Key header is missing, or the key is unknown, revoked or replaced.	`Error`
`403`	The key is valid but may not do this (for example an agent key approving its own held action).	`Error`
`413`	The request body is over 1048576 bytes.	`Error`
`422`	Validation Error	`HTTPValidationError`
`429`	Rate limit or monthly quota reached. Wait for the number of seconds in Retry-After when it is sent.	`Error`

Try it

Your API key X-API-Key Remember the key in this tab onlyRequest body application/json

This call changes data in the account the key belongs to.

The request goes from your browser straight to this site. Your key is not stored unless you tick the box, and then only in this tab's session storage.

Code

curl -sS -X POST 'https://cainstudio.online/fabric/decisions' \
  -H "X-API-Key: $CAIN_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"path": "/tools/send_email", "payload": {"to": "ops@example.com", "subject": "Weekly report"}, "agent_id": "my-agent", "chain_id": "run-001", "record": false, "provenance": {"to": "user"}}'

import json, os, urllib.request

req = urllib.request.Request('https://cainstudio.online/fabric/decisions', method='POST',
    headers={"X-API-Key": os.environ["CAIN_API_KEY"], "Content-Type": "application/json"},
    data=json.dumps({
      "path": "/tools/send_email",
      "payload": {
        "to": "ops@example.com",
        "subject": "Weekly report"
      },
      "agent_id": "my-agent",
      "chain_id": "run-001",
      "record": False,
      "provenance": {
        "to": "user"
      }
    }).encode())
with urllib.request.urlopen(req, timeout=60) as r:
    print(r.status, json.load(r))

const res = await fetch("https://cainstudio.online/fabric/decisions", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.CAIN_API_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "path": "/tools/send_email",
    "payload": {
      "to": "ops@example.com",
      "subject": "Weekly report"
    },
    "agent_id": "my-agent",
    "chain_id": "run-001",
    "record": false,
    "provenance": {
      "to": "user"
    }
  }),
});
console.log(res.status, await res.json());

In application code the SDK wraps this call for you: @cainstudio.guard() on a function sends its name and arguments here and only runs it on ALLOW. See the Python SDK.

Schemas used

Decision · Error · HTTPValidationError · ValidationError · DecisionRequest

← List this tenant's recent Fabric decisions · all 81 Trust Fabric calls · Live feed of this tenant's decisions (Server-Sent Events) →

Try CAIN-42 on your own agents

Create a free account and every new account starts with a 30-day trial of the full platform. Or try the sandbox first, with no account at all.

Create a free account → · Try the sandbox · See the whole ecosystem