{"components":{"headers":{"Genius-Budget-Mode":{"description":"Whether the decision ran in mock, test, or live budget mode.","schema":{"enum":["mock","test","live"],"type":"string"}},"Genius-Council-Used":{"description":"Whether council analysis was used for this decision.","schema":{"type":"boolean"}},"Genius-Intelligence-Path":{"description":"Whether the decision used low, standard, or full intelligence depth.","schema":{"enum":["low","standard","full"],"type":"string"}},"Genius-Research-Used":{"description":"Whether external research was used for this decision.","schema":{"type":"boolean"}},"Genius-Version":{"description":"Current Genius protocol version used for request validation and response compatibility.","schema":{"example":"2026-04-01","type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying after a rate-limit response.","schema":{"type":"integer"}},"X-Cosy-Trace-Id":{"description":"Trace identifier for the governed decision when available.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Maximum number of Genius API calls allowed in the current window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining Genius API calls in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp for when the current Genius rate-limit window resets.","schema":{"type":"integer"}}},"parameters":{"GeniusVersion":{"description":"Optional Genius protocol version. Unsupported versions fail with genius_version_unsupported.","in":"header","name":"Genius-Version","required":false,"schema":{"default":"2026-04-01","type":"string"}},"IdempotencyKey":{"description":"Replays the same completed governed result for the same principal, route, and request body.","in":"header","name":"Idempotency-Key","required":false,"schema":{"type":"string"}},"ProofPacketId":{"in":"path","name":"id","required":true,"schema":{"type":"string"}},"TransactionId":{"in":"path","name":"id","required":true,"schema":{"type":"string"}}},"schemas":{"CommunicationTransaction":{"additionalProperties":true,"description":"Governed CommunicationTransaction object returned by the Go decision engine.","type":"object"},"CommunicationTransactionCreateRequest":{"properties":{"asks":{"items":{"additionalProperties":true,"type":"object"},"type":"array"},"attribution_signals":{"items":{"additionalProperties":true,"type":"object"},"type":"array"},"authority_result":{"additionalProperties":true,"type":"object"},"authority_signals":{"items":{"additionalProperties":true,"type":"object"},"type":"array"},"body_excerpt":{"type":"string"},"claims":{"items":{"additionalProperties":true,"type":"object"},"type":"array"},"deadlines":{"items":{"additionalProperties":true,"type":"object"},"type":"array"},"documents_referenced":{"items":{"additionalProperties":true,"type":"object"},"type":"array"},"id":{"type":"string"},"implied_asks":{"items":{"additionalProperties":true,"type":"object"},"type":"array"},"participants":{"items":{"$ref":"#/components/schemas/PreCommitParticipant"},"type":"array"},"possible_commitments":{"items":{"additionalProperties":true,"type":"object"},"type":"array"},"pressure_signals":{"items":{"additionalProperties":true,"type":"object"},"type":"array"},"source":{"type":"string"},"source_message_id":{"type":"string"},"source_surface":{"type":"string"},"source_thread_id":{"type":"string"},"subject":{"type":"string"}},"required":["id","source","source_surface","source_message_id","source_thread_id","participants","subject","body_excerpt","claims","asks","implied_asks","deadlines","documents_referenced","authority_signals","pressure_signals","attribution_signals","possible_commitments","authority_result"],"type":"object"},"CommunicationTransactionEnvelope":{"properties":{"id":{"type":"string"},"object":{"const":"communication_transaction","type":"string"},"trace_id":{"type":"string"},"transaction":{"$ref":"#/components/schemas/CommunicationTransaction"}},"required":["object","id","trace_id","transaction"],"type":"object"},"DecisionEnvelope":{"properties":{"action_gate":{"properties":{"action_type":{"type":"string"},"allowed":{"type":"boolean"},"approval_required":{"type":"boolean"},"blocked_reason":{"type":"string"},"recommended_action":{"type":"string"},"requires_human_review":{"type":"boolean"},"signal":{"properties":{"state":{"enum":["green","amber","red","grey"],"type":"string"}},"required":["state"],"type":"object"}},"required":["action_type","allowed","blocked_reason","requires_human_review","approval_required","recommended_action","signal"],"type":"object"},"id":{"type":"string"},"object":{"const":"decision","type":"string"},"proof_packet_id":{"type":"string"},"safe_reply":{"additionalProperties":true,"type":"object"},"safe_resolution":{"properties":{"action_gate_effect":{"type":"string"},"can_forward_raw_content":{"type":"boolean"},"can_send":{"type":"boolean"},"headline":{"type":"string"},"lane":{"enum":["VERIFY_OUT_OF_BAND","ROUTE_FOR_REVIEW","HOLD_ACTION"],"type":"string"},"next_step_copy":{"type":"string"},"ordered_requirements":{"items":{"type":"string"},"type":"array"},"owner_required":{"type":"boolean"},"proof_ready":{"type":"boolean"},"reason_codes":{"items":{"type":"string"},"type":"array"}},"required":["lane","headline","next_step_copy","proof_ready","action_gate_effect","can_send","can_forward_raw_content","reason_codes"],"type":"object"},"safest_move":{"additionalProperties":true,"type":"object"},"signal":{"$ref":"#/components/schemas/DecisionSignal"},"source_transaction":{"$ref":"#/components/schemas/CommunicationTransaction"},"status":{"enum":["completed"],"type":"string"},"summary":{"type":"string"},"trace_id":{"type":"string"},"traffic_light":{"properties":{"label":{"enum":["safe","caution","unsafe","unknown"],"type":"string"},"state":{"enum":["green","amber","red","grey"],"type":"string"}},"required":["state","label"],"type":"object"}},"required":["object","id","status","traffic_light","signal","summary","safest_move","safe_reply","action_gate","proof_packet_id","trace_id","source_transaction"],"type":"object"},"DecisionSignal":{"properties":{"state":{"enum":["green","amber","red","grey"],"type":"string"},"type":{"const":"decision_dot","type":"string"}},"required":["type","state"],"type":"object"},"ErrorDictionaryEntry":{"properties":{"code":{"type":"string"},"docs_url":{"type":"string"},"http_status":{"type":"integer"},"meaning":{"type":"string"},"message":{"type":"string"},"resolution":{"type":"string"},"type":{"enum":["invalid_request_error","authentication_error","not_found_error","idempotency_error","rate_limit_error","service_unavailable_error"],"type":"string"}},"required":["code","type","http_status","message","meaning","resolution","docs_url"],"type":"object"},"ErrorDictionaryEntryEnvelope":{"properties":{"error":{"$ref":"#/components/schemas/ErrorDictionaryEntry"},"object":{"const":"error_dictionary_entry","type":"string"}},"required":["object","error"],"type":"object"},"ErrorDictionaryEnvelope":{"properties":{"errors":{"items":{"$ref":"#/components/schemas/ErrorDictionaryEntry"},"type":"array"},"object":{"const":"error_dictionary","type":"string"},"version":{"type":"string"}},"required":["object","version","errors"],"type":"object"},"PreCommitParticipant":{"properties":{"email":{"type":"string"},"name":{"type":"string"},"role":{"type":"string"}},"required":["name","email","role"],"type":"object"},"ProofPacket":{"additionalProperties":true,"description":"Persisted proof packet snapshot with raw provider outputs omitted by default.","type":"object"},"ProofPacketEnvelope":{"properties":{"id":{"type":"string"},"object":{"const":"proof_packet","type":"string"},"proof_packet":{"$ref":"#/components/schemas/ProofPacket"},"trace_id":{"type":"string"},"transaction_id":{"type":"string"}},"required":["object","id","transaction_id","trace_id","proof_packet"],"type":"object"},"V1ErrorEnvelope":{"properties":{"error":{"properties":{"code":{"type":"string"},"docs_url":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"trace_id":{"type":"string"},"type":{"enum":["invalid_request_error","authentication_error","not_found_error","idempotency_error","rate_limit_error","service_unavailable_error"],"type":"string"}},"required":["type","code","message","request_id","trace_id","docs_url"],"type":"object"}},"required":["error"],"type":"object"}},"securitySchemes":{"ActorHeaders":{"description":"Pair with X-Cosy-Actor-Token. Public API keys are not live yet.","in":"header","name":"X-Cosy-Actor-Id","type":"apiKey"},"ActorTokenHeaders":{"description":"Pair with X-Cosy-Actor-Id.","in":"header","name":"X-Cosy-Actor-Token","type":"apiKey"}}},"info":{"description":"AI-discoverable decision API for consequential communication. Call Genius before consequential action. Genius informs; it does not grant automatic permission. Deterministic PreCommit governance remains final.","title":"Genius Decision API","version":"0.1.0"},"openapi":"3.1.0","paths":{"/v1/communication_transactions":{"post":{"description":"Runs the existing Go PreCommit engine and returns a public communication transaction object.","parameters":[{"$ref":"#/components/parameters/GeniusVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommunicationTransactionCreateRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommunicationTransaction"}}},"description":"Governed communication transaction created","headers":{"Genius-Version":{"$ref":"#/components/headers/Genius-Version"},"X-Cosy-Trace-Id":{"$ref":"#/components/headers/X-Cosy-Trace-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorEnvelope"}}},"description":"Invalid request or fail-closed validation failure"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorEnvelope"}}},"description":"Authentication required"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorEnvelope"}}},"description":"Idempotency conflict"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorEnvelope"}}},"description":"Rate limit exceeded","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorEnvelope"}}},"description":"Upstream analysis unavailable"}},"summary":"Create a governed communication decision"}},"/v1/communication_transactions/{id}":{"get":{"parameters":[{"$ref":"#/components/parameters/GeniusVersion"},{"$ref":"#/components/parameters/TransactionId"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommunicationTransactionEnvelope"}}},"description":"Governed communication transaction fetched","headers":{"Genius-Version":{"$ref":"#/components/headers/Genius-Version"},"X-Cosy-Trace-Id":{"$ref":"#/components/headers/X-Cosy-Trace-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorEnvelope"}}},"description":"Authentication required"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorEnvelope"}}},"description":"Transaction not found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorEnvelope"}}},"description":"Rate limit exceeded","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}}},"summary":"Fetch a persisted governed communication decision"}},"/v1/decisions":{"post":{"description":"Call before consequential communication or agent action. Typical use cases include supplier bank-detail changes, urgent payment pressure, commitment-risk replies, refund or credit promises, and procurement updates. Read action_gate.allowed first. Allowed does not mean auto-send or autonomous approval.","parameters":[{"$ref":"#/components/parameters/GeniusVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"examples":{"supplier_bank_detail_change":{"summary":"Supplier bank-detail change request","value":{"asks":[],"attribution_signals":[],"authority_result":{},"authority_signals":[],"body_excerpt":"Please update our bank details before the next invoice is paid. The invoice is due this week.","claims":[],"deadlines":[],"documents_referenced":[],"id":"supplier_bank_change_001","implied_asks":[],"participants":[{"email":"accounts@supplier.example","name":"Supplier Accounts","role":"sender"},{"email":"ap@buyer.example","name":"AP Team","role":"recipient"}],"possible_commitments":[],"pressure_signals":[],"source":"email","source_message_id":"msg_bank_001","source_surface":"finance_shared_inbox","source_thread_id":"thr_bank_001","subject":"Updated bank details for upcoming payment"}}},"schema":{"$ref":"#/components/schemas/CommunicationTransactionCreateRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"examples":{"blocked_bank_change":{"summary":"Blocked supplier bank-detail change flow","value":{"action_gate":{"action_type":"reply","allowed":false,"approval_required":false,"blocked_reason":"Payment-detail change request is unresolved and high consequence.","recommended_action":"Stop and verify through a known supplier contact.","requires_human_review":true,"signal":{"state":"red"}},"id":"dec_bank_change_001","object":"decision","proof_packet_id":"ppk_bank_change_001","safe_reply":{"allowed_to_insert":false,"draft":""},"safe_resolution":{"action_gate_effect":"blocked_until_verified","can_forward_raw_content":false,"can_send":false,"headline":"Verify this request through a known supplier or finance contact route before taking action.","lane":"VERIFY_OUT_OF_BAND","next_step_copy":"Verify this request through a known supplier or finance contact route before taking action.","ordered_requirements":["independent verification first","record the verification outcome before any further action"],"owner_required":false,"proof_ready":false,"reason_codes":["payment_or_supplier_risk","material_truth_gap","unsafe_or_blocked_verdict"]},"safest_move":{"move_type":"verify_known_contact","rationale":"Verify the change through a previously known supplier contact before any reply or update."},"signal":{"state":"red","type":"decision_dot"},"source_transaction":{},"status":"completed","summary":"The message asks for a payment-related bank-detail change that should not be accepted from email alone.","trace_id":"trace_bank_change_001","traffic_light":{"label":"unsafe","state":"red"}}}},"schema":{"$ref":"#/components/schemas/DecisionEnvelope"}}},"description":"Governed decision created","headers":{"Genius-Budget-Mode":{"$ref":"#/components/headers/Genius-Budget-Mode"},"Genius-Council-Used":{"$ref":"#/components/headers/Genius-Council-Used"},"Genius-Intelligence-Path":{"$ref":"#/components/headers/Genius-Intelligence-Path"},"Genius-Research-Used":{"$ref":"#/components/headers/Genius-Research-Used"},"Genius-Version":{"$ref":"#/components/headers/Genius-Version"},"X-Cosy-Trace-Id":{"$ref":"#/components/headers/X-Cosy-Trace-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorEnvelope"}}},"description":"Invalid request or fail-closed validation failure"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorEnvelope"}}},"description":"Authentication required"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorEnvelope"}}},"description":"Idempotency conflict"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorEnvelope"}}},"description":"Rate limit exceeded","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorEnvelope"}}},"description":"Upstream analysis unavailable"}},"summary":"Create an AI-native governed decision"}},"/v1/decisions/{id}":{"get":{"parameters":[{"$ref":"#/components/parameters/GeniusVersion"},{"$ref":"#/components/parameters/TransactionId"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecisionEnvelope"}}},"description":"Governed decision fetched","headers":{"Genius-Budget-Mode":{"$ref":"#/components/headers/Genius-Budget-Mode"},"Genius-Council-Used":{"$ref":"#/components/headers/Genius-Council-Used"},"Genius-Intelligence-Path":{"$ref":"#/components/headers/Genius-Intelligence-Path"},"Genius-Research-Used":{"$ref":"#/components/headers/Genius-Research-Used"},"Genius-Version":{"$ref":"#/components/headers/Genius-Version"},"X-Cosy-Trace-Id":{"$ref":"#/components/headers/X-Cosy-Trace-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorEnvelope"}}},"description":"Authentication required"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorEnvelope"}}},"description":"Decision not found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorEnvelope"}}},"description":"Rate limit exceeded","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}}},"summary":"Fetch a persisted AI-native governed decision"}},"/v1/errors":{"get":{"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDictionaryEnvelope"}}},"description":"Public machine-readable Genius error dictionary","headers":{"Genius-Version":{"$ref":"#/components/headers/Genius-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}}},"summary":"Fetch the public Genius error dictionary"}},"/v1/errors/{code}":{"get":{"parameters":[{"in":"path","name":"code","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorDictionaryEntryEnvelope"}}},"description":"One Genius error dictionary entry","headers":{"Genius-Version":{"$ref":"#/components/headers/Genius-Version"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorEnvelope"}}},"description":"Error code not found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorEnvelope"}}},"description":"Rate limit exceeded","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}}},"summary":"Fetch one Genius error dictionary entry"}},"/v1/proof_packets/{id}":{"get":{"parameters":[{"$ref":"#/components/parameters/GeniusVersion"},{"$ref":"#/components/parameters/ProofPacketId"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProofPacketEnvelope"}}},"description":"Proof packet fetched","headers":{"Genius-Version":{"$ref":"#/components/headers/Genius-Version"},"X-Cosy-Trace-Id":{"$ref":"#/components/headers/X-Cosy-Trace-Id"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorEnvelope"}}},"description":"Authentication required"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorEnvelope"}}},"description":"Proof packet not found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorEnvelope"}}},"description":"Rate limit exceeded","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}}},"summary":"Fetch the proof packet for a governed decision"}}},"security":[{"ActorHeaders":[]}],"servers":[{"description":"Current server origin","url":"/"}]}