1. Send the communication
Call POST /v1/decisions before a reply, approval, or document action that could create consequence.
Genius API Quickstart
Start with one decision call.
If your workflow may create commitment, authority, reputational, legal, or money consequences, call Genius before taking action.
3-step integration
The shortest safe way to integrate
2. Read the control fields
Check action_gate.allowed first. Then read signal and safest_next_move. If action_gate.allowed is false, stop and escalate.
3. Keep audit references
Keep proof_packet_id and trace_id for audit and later review after the control decision has been made.
Curl example
POST /v1/decisions in one call
Start with a single decision request. Add Genius-Version and Idempotency-Keyon day one so retries and upgrades stay predictable.
The example uses the current actor authentication headers X-Cosy-Actor-Id and X-Cosy-Actor-Token. They are actor authentication headers for the current protocol, not a separate product identity.
curl https://app.precommit.ai/v1/decisions \
-X POST \
-H "Content-Type: application/json" \
-H "Genius-Version: 2026-04-01" \
-H "Idempotency-Key: demo-decision-001" \
-H "X-Cosy-Actor-Id: YOUR_ACTOR_ID" \
-H "X-Cosy-Actor-Token: YOUR_ACTOR_TOKEN" \
-d '{
"id": "demo_email_001",
"source": "gmail",
"source_surface": "gmail_thread",
"source_message_id": "msg_001",
"source_thread_id": "thr_001",
"participants": [
{ "name": "Tom", "email": "[email protected]", "role": "sender" },
{ "name": "James", "email": "[email protected]", "role": "recipient" }
],
"subject": "Can you confirm you're happy to proceed?",
"body_excerpt": "If you can confirm you're happy to proceed today, I'll send over the agreement for signature.",
"claims": [],
"asks": [],
"implied_asks": [],
"deadlines": [],
"documents_referenced": [],
"authority_signals": [],
"pressure_signals": [],
"attribution_signals": [],
"possible_commitments": [],
"authority_result": {}
}'Safety rule
Allowed does not mean send
Genius informs; it does not grant automatic permission. Even when action_gate.allowed is true, the safe pattern is to prepare the next step under accountable human or organisational control.
Example response
Read the action gate, signal, and safest next move first
{
"object": "decision",
"id": "dec_123",
"status": "completed",
"traffic_light": {
"state": "amber",
"label": "caution"
},
"signal": {
"type": "decision_dot",
"state": "amber"
},
"summary": "This reply could be treated as agreement before the final terms are reviewed.",
"safest_move": {
"move_type": "review_terms_before_confirming",
"rationale": "Ask for the final written terms before confirming anything that could bind you."
},
"safe_reply": {
"allowed_to_insert": false,
"draft": ""
},
"action_gate": {
"action_type": "reply",
"allowed": false,
"requires_human_review": true,
"approval_required": false,
"blocked_reason": "The message asks for a commitment before final terms are reviewed.",
"recommended_action": "Review the terms first and reply without confirming acceptance.",
"signal": {
"state": "amber"
}
},
"proof_packet_id": "ppk_123",
"trace_id": "trace_123"
}action_gate.allowed
The first field an agent should read. False means stop before acting.
signal.state
A compact, state-safe indicator for UI or agent workflows: green, amber, red, or grey.
safest_move.rationale
The governed next step to take once the action gate and signal have been read.
summary
Plain-English explanation that supports the control decision.
proof_packet_id
Secondary audit reference to fetch later if you need persisted governed proof for review or support after the action decision is made.
trace_id
Secondary support and audit reference for debugging, support, and internal review after the control path is complete.
ActionGate
What an agent should do next
This is the primary agent control field. If `false`, do not continue with the action. Escalate to a human or ask for review first. If `true`, read `signal` and `safest_move` next before using any secondary audit references.
if (!decision.action_gate.allowed) {
// Stop here. Ask for review before acting.
return {
status: "blocked",
next_step: decision.safest_move.rationale,
};
}
return {
status: "reviewed",
next_step: decision.safest_move.rationale,
draft: decision.safe_reply.allowed_to_insert ? decision.safe_reply.draft : null,
note: "Genius informs; it does not grant automatic permission to send.",
};Audit references
Keep proof_packet_id and trace_id for audit, support, and later review. Use GET /v1/proof_packets/{id} only when you need the persisted governed proof object after the action decision has already been read.
Genius-Version
Current supported version: 2026-04-01. You can omit the header and Genius will default to the current version.
Concrete examples
When an agent should call Genius
Supplier bank-detail change
When to call: Before AP replies, updates supplier records, or acts on a payment-detail change sent by email.
Request shape: Email-style communication transaction with subject, body_excerpt, sender, recipient, and payment context.
Response shape: Unsafe or high-caution decision with blocked action_gate, a governed safest move to verify via a known supplier contact, and audit references for later review.
Safest next move: Do not update bank details from email alone. Verify via a known supplier contact path and record the review.
Audit / Autograph: Keep proof_packet_id for audit after the control decision. If a human explicitly records the review in PreCommit, Autograph can bind that reviewed communication to accountable approval or blocked review.
Must not do automatically: Do not auto-send, auto-approve, or auto-update supplier master data because a signal came back green or amber.
Urgent payment pressure
When to call: Before an agent or AP operator replies to an urgent payment request that relies on time pressure or senior-name authority.
Request shape: Communication transaction including urgency cues, sender identity, subject, and requested action.
Response shape: Unsafe or caution decision highlighting authority gaps, pressure signals, and blocked or reviewed action_gate.
Safest next move: Verify through an internal known channel and escalate to the accountable finance or risk owner.
Audit / Autograph: Proof packet captures the governed result after the risk gate is read. Autograph can record that payment approval was reviewed or blocked before any action.
Must not do automatically: Do not interpret urgency as authority. Do not draft a reply that implies payment approval automatically.
Contract commitment reply
When to call: Before sending a reply that may imply acceptance, scope agreement, delivery commitment, or liability.
Request shape: Reply candidate or message excerpt with possible commitment language.
Response shape: Decision object explaining commitment risk, safest move, and whether a bounded safe reply may be inserted.
Safest next move: Clarify terms or request the final written terms before confirming anything binding.
Audit / Autograph: Proof packet records the governed communication state as a secondary audit object. Autograph can record reviewed-before-action or blocked-review status.
Must not do automatically: Do not auto-send the safe reply draft. Allowed means prepare under accountable control, not autonomous send.
AI agent about to send an external message
When to call: Before an agent sends an externally-visible message that could create consequence for a person or organisation.
Request shape: Proposed outbound message with participants, subject, body_excerpt, and action context.
Response shape: Decision with action_gate, signal, safest_move, and secondary audit references.
Safest next move: Use the governed safest move and draft only as a bounded input to human or organisational review.
Audit / Autograph: Proof packet shows what was checked after the control decision. Autograph can record who accepted accountability for the reviewed output.
Must not do automatically: Do not treat allowed=true as a send permission. Genius is a risk gate, not an autonomous execution grant.
Support agent about to promise refund or credit
When to call: Before a support workflow promises a refund, credit, waiver, or exception with financial or policy consequence.
Request shape: Outbound support reply candidate with issue summary, customer message context, and proposed promise.
Response shape: Decision showing money, authority, or exception risk and whether escalation is required.
Safest next move: Restate current status narrowly and escalate to the accountable owner if authority is missing.
Audit / Autograph: Proof packet supports review and dispute handling later as a secondary audit reference. Autograph can show that the risky promise was reviewed before action.
Must not do automatically: Do not auto-grant commercial concessions because the tool did not block.
Procurement agent about to approve supplier update
When to call: Before procurement or a workflow agent approves a supplier setup or supplier-record change with control implications.
Request shape: Supplier update request with identity, requested change, and any approval or authority context.
Response shape: Decision highlighting authority gaps, missing protections, and safest next move.
Safest next move: Route through procurement controls and require verification before any approval step is completed.
Audit / Autograph: Proof packet anchors the governed decision for audit after the control step. Autograph can record the accountable review if a human approves or blocks the step.
Must not do automatically: Do not use Genius as a replacement for supplier onboarding controls or finance control policy.
Required headers
Idempotency, rate limits, and safe retries
Idempotency-Key
Send an Idempotency-Key on POST requests so client retries do not create duplicate decisions or proof packets.
Rate-limit headers
- X-RateLimit-Limit
- X-RateLimit-Remaining
- X-RateLimit-Reset
- Retry-After on 429
If a Genius call fails, read error.code and consult /api/errors.
Test mode note
Genius test mode is for deterministic integration and mock provider paths. Live mode is for governed use on real communication once access is approved.
Raw content is not stored by default. Genius is not legal advice and not a fraud guarantee.