{"openapi":"3.1.0","info":{"title":"Plutonious Tool Gateway","description":"The single governed path to every external tool / side-effect. Default-deny, fail-closed, taint-aware, budgeted, kill-switchable.","version":"1.0"},"paths":{"/v1/tools/invoke":{"post":{"summary":"Invoke Tool","description":"The one endpoint that performs a governed side-effect.\n\nReturns 200 with the result on success, or a 4xx/5xx with a stable denial\nreason. Every outcome — allow or deny — is audited (WORM, DPDP-minimized).","operationId":"invoke_tool_v1_tools_invoke_post","parameters":[{"name":"x-spiffe-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Spiffe-Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolCallRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolCallResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/manifests":{"post":{"summary":"Register Manifest","description":"Register/replace an agent manifest — the authz source of truth.\nTODO(prod): restrict this control-plane route to the registry service's SVID\nvia OPA (default-deny); agents cannot self-grant scope.","operationId":"register_manifest_v1_manifests_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentManifest"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":{"type":"string"},"type":"object","title":"Response Register Manifest V1 Manifests Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/kill/tool/{tool_name}":{"post":{"summary":"Kill Tool","description":"Trip a single tool's kill switch (fail-closed). Idempotent.","operationId":"kill_tool_v1_kill_tool__tool_name__post","parameters":[{"name":"tool_name","in":"path","required":true,"schema":{"type":"string","title":"Tool Name"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Kill Tool V1 Kill Tool  Tool Name  Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/kill/tool/{tool_name}/reset":{"post":{"summary":"Reset Tool","description":"Re-enable a single tool after a kill. Operator-only.","operationId":"reset_tool_v1_kill_tool__tool_name__reset_post","parameters":[{"name":"tool_name","in":"path","required":true,"schema":{"type":"string","title":"Tool Name"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Reset Tool V1 Kill Tool  Tool Name  Reset Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/kill/global":{"post":{"summary":"Kill Global","description":"Panic button: trip the global kill switch — every tool denied at once.\nThis is the SEBI 'kill-switch as last line of defence' at the gateway scope.","operationId":"kill_global_v1_kill_global_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":{"type":"boolean"},"type":"object","title":"Response Kill Global V1 Kill Global Post"}}}}}}},"/v1/kill/global/reset":{"post":{"summary":"Reset Global","description":"Clear the global kill switch (operator-only).","operationId":"reset_global_v1_kill_global_reset_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":{"type":"boolean"},"type":"object","title":"Response Reset Global V1 Kill Global Reset Post"}}}}}}},"/v1/tools":{"get":{"summary":"List Tools","description":"List registered tools with their side-effect class + gates (no handlers).","operationId":"list_tools_v1_tools_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Response List Tools V1 Tools Get"}}}}}}},"/v1/audit/tail":{"get":{"summary":"Audit Tail","description":"Return the most recent audit records (dev/test). DPDP: no raw args here.\nTODO(prod): this is served from the append-only audit service, not memory.","operationId":"audit_tail_v1_audit_tail_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":100,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true},"title":"Response Audit Tail V1 Audit Tail Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/healthz":{"get":{"summary":"Healthz","operationId":"healthz_healthz_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":{"type":"string"},"type":"object","title":"Response Healthz Healthz Get"}}}}}}}},"components":{"schemas":{"AgentManifest":{"properties":{"agent_id":{"type":"string","title":"Agent Id"},"purpose":{"type":"string","title":"Purpose"},"autonomy":{"$ref":"#/components/schemas/AutonomyLevel"},"model_tier":{"type":"string","enum":["frontier_llm","mid_llm","slm","ml","rules"],"title":"Model Tier"},"inputs":{"items":{"type":"string"},"type":"array","title":"Inputs"},"outputs":{"items":{"type":"string"},"type":"array","title":"Outputs"},"tools_allowed":{"items":{"type":"string"},"type":"array","title":"Tools Allowed"},"memory_scopes":{"items":{"type":"string"},"type":"array","title":"Memory Scopes"},"human_approval_required":{"type":"boolean","title":"Human Approval Required"},"kpis":{"additionalProperties":{"type":"string"},"type":"object","title":"Kpis"},"failure_modes":{"items":{"type":"string"},"type":"array","title":"Failure Modes"}},"type":"object","required":["agent_id","purpose","autonomy","model_tier","inputs","outputs","tools_allowed","memory_scopes","human_approval_required","kpis","failure_modes"],"title":"AgentManifest"},"AutonomyLevel":{"type":"string","enum":["L0_advisory","L1_assisted","L2_supervised","L3_conditional"],"title":"AutonomyLevel"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"SideEffectClass":{"type":"string","enum":["read","write","irreversible"],"title":"SideEffectClass"},"Taint":{"type":"string","enum":["trusted","untrusted","quarantined"],"title":"Taint"},"ToolCallRequest":{"properties":{"correlation_id":{"type":"string","format":"uuid","title":"Correlation Id","description":"ties to the DecisionLog row"},"tool":{"type":"string","title":"Tool","description":"must be in caller manifest.tools_allowed"},"taint":{"$ref":"#/components/schemas/Taint","default":"untrusted"},"args":{"additionalProperties":true,"type":"object","title":"Args"},"human_approval_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Human Approval Token"},"est_tokens":{"type":"integer","title":"Est Tokens","default":0},"est_rupees":{"anyOf":[{"type":"number"},{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"}],"title":"Est Rupees","default":"0"}},"type":"object","required":["correlation_id","tool"],"title":"ToolCallRequest","description":"A governed tool invocation. NOTE: agent_id is intentionally absent — it is\ntaken from the verified SPIFFE identity, never the body."},"ToolCallResponse":{"properties":{"call_id":{"type":"string","format":"uuid","title":"Call Id"},"correlation_id":{"type":"string","format":"uuid","title":"Correlation Id"},"tool":{"type":"string","title":"Tool"},"side_effect":{"$ref":"#/components/schemas/SideEffectClass"},"allowed":{"type":"boolean","title":"Allowed"},"result":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Result"},"denied_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Denied Reason"},"ts":{"type":"string","format":"date-time","title":"Ts"}},"type":"object","required":["call_id","correlation_id","tool","side_effect","allowed","ts"],"title":"ToolCallResponse"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}