{"openapi":"3.1.0","info":{"title":"AgentTX Pilot API","version":"0.2.0","description":"Sandbox-only deterministic spend authorization and privacy-preserving pilot evidence. No endpoint moves funds."},"servers":[{"url":"https://api.agenttx.cc"}],"paths":{"/v1/pilot/agents":{"post":{"operationId":"registerPilotAgent","summary":"Register an Agent and receive its bearer credential once","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentRegistration"}}}},"responses":{"201":{"description":"Registered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentCredential"}}}},"400":{"description":"Request rejected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request rejected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request rejected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/pilot/agents/me":{"get":{"operationId":"getPilotAgent","summary":"Read the authenticated Agent's activation evidence","security":[{"pilotAgentCredential":[]}],"responses":{"200":{"description":"Agent status","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Request rejected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/pilot/spend-intents":{"post":{"operationId":"evaluatePilotSpendIntent","summary":"Evaluate one spend proposal without executing payment","security":[{"pilotAgentCredential":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]+$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SpendIntent"}}}},"responses":{"200":{"description":"Idempotent replay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SpendDecision"}}}},"201":{"description":"New decision","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SpendDecision"}}}},"400":{"description":"Request rejected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Request rejected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request rejected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request rejected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/pilot/human-sessions":{"post":{"operationId":"startPolicyLabSession","summary":"Start a privacy-preserving Policy Lab session","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["participantId"],"properties":{"participantId":{"type":"string","format":"uuid"}}}}}},"responses":{"201":{"description":"Session started","content":{"application/json":{"schema":{"type":"object","required":["sessionId","sessionToken","sandbox"],"properties":{"sessionId":{"type":"string"},"sessionToken":{"type":"string","writeOnly":true,"pattern":"^atx_human_"},"sandbox":{"const":true}}}}}},"400":{"description":"Request rejected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request rejected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request rejected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/pilot/human-sessions/complete":{"post":{"operationId":"completePolicyLabSession","summary":"Issue a proof after three server-evaluated Policy Lab outcomes","security":[{"humanSessionCredential":[]}],"responses":{"200":{"description":"Completion proof","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HumanProofReceipt"}}}},"400":{"description":"Request rejected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Request rejected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/pilot/human-sessions/evaluate":{"post":{"operationId":"evaluatePolicyLabRequest","summary":"Evaluate and record one Policy Lab request on the server","security":[{"humanSessionCredential":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["scenarioId","monthlyBudget","spent","perTransaction","trustedMerchant","merchant","amount","category"],"properties":{"scenarioId":{"enum":["trusted","unknown","over-limit"]},"monthlyBudget":{"type":"number","minimum":20,"maximum":250},"spent":{"type":"number","minimum":0,"maximum":250},"perTransaction":{"type":"number","minimum":1,"maximum":25},"trustedMerchant":{"type":"string"},"merchant":{"type":"string"},"amount":{"type":"number","exclusiveMinimum":0,"maximum":250},"category":{"type":"string"}}}}}},"responses":{"200":{"description":"Recorded deterministic decision","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HumanPolicyDecision"}}}},"400":{"description":"Request rejected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Request rejected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request rejected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/pilot/stats":{"get":{"operationId":"getPilotStats","summary":"Read aggregate pilot usage counts","responses":{"200":{"description":"Aggregate counts","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/pilot/evidence":{"get":{"operationId":"getPilotEvidence","summary":"Read anonymous completion commitments","responses":{"200":{"description":"Public evidence","content":{"application/json":{"schema":{"type":"object","required":["completedHumanUsers","proofs","phaseOneTarget","sandbox"],"properties":{"completedHumanUsers":{"type":"integer","minimum":0},"proofs":{"type":"array","items":{"$ref":"#/components/schemas/HumanProof"}},"phaseOneTarget":{"const":10},"sandbox":{"const":true}}}}}}}}}},"components":{"securitySchemes":{"pilotAgentCredential":{"type":"http","scheme":"bearer","bearerFormat":"atx_pilot_..."},"humanSessionCredential":{"type":"http","scheme":"bearer","bearerFormat":"atx_human_..."}},"schemas":{"AgentRegistration":{"type":"object","additionalProperties":false,"required":["name","externalAgentId"],"properties":{"name":{"type":"string","minLength":2,"maxLength":80},"externalAgentId":{"type":"string","minLength":3,"maxLength":200},"framework":{"type":"string","minLength":1,"maxLength":80},"homepage":{"type":"string","format":"uri","pattern":"^https://"}}},"AgentCredential":{"type":"object","required":["agentId","secret","sandbox"],"properties":{"agentId":{"type":"string"},"secret":{"type":"string","writeOnly":true,"pattern":"^atx_pilot_"},"sandbox":{"const":true}}},"SpendIntent":{"type":"object","additionalProperties":false,"required":["merchant","amount","category","purpose","resourceUrl","taskId"],"properties":{"merchant":{"type":"string","minLength":3,"maxLength":253},"amount":{"type":"number","exclusiveMinimum":0,"maximum":1000000},"category":{"type":"string","minLength":1,"maxLength":100},"purpose":{"type":"string","minLength":3,"maxLength":500},"resourceUrl":{"type":"string","format":"uri","pattern":"^https://"},"taskId":{"type":"string","minLength":1,"maxLength":200},"riskScore":{"type":"integer","minimum":0,"maximum":100,"default":0}}},"SpendDecision":{"type":"object","required":["intentId","decision","sandbox","paymentExecuted","replayed"],"properties":{"intentId":{"type":"string"},"decision":{"enum":["ALLOW","REQUIRE_APPROVAL","DENY"]},"reasonCodes":{"type":"array","items":{"type":"string"}},"matchedRuleIds":{"type":"array","items":{"type":"string"}},"sandbox":{"const":true},"paymentExecuted":{"const":false},"replayed":{"type":"boolean"}}},"HumanPolicyDecision":{"type":"object","required":["decision","title","reasonCodes","facts","recordedOutcomes","scenarioMatched","sandbox","paymentExecuted"],"properties":{"decision":{"enum":["ALLOW","REQUIRE_APPROVAL","DENY"]},"title":{"type":"string"},"reasonCodes":{"type":"array","items":{"type":"string"}},"facts":{"type":"array","items":{"type":"string"}},"recordedOutcomes":{"type":"array","items":{"enum":["ALLOW","REQUIRE_APPROVAL","DENY"]}},"scenarioMatched":{"type":"boolean","description":"True only when this decision matches the selected Policy Lab scenario and advances completion"},"sandbox":{"const":true},"paymentExecuted":{"const":false}}},"HumanProofReceipt":{"type":"object","required":["proofCode","proofHash","completedAt","counted","sandbox"],"properties":{"proofCode":{"type":"string","pattern":"^ATX-(?:[A-F0-9]{32}|[A-F0-9]{10})$","description":"New receipts use 128-bit (32 hex) codes; 10-hex codes are accepted only for legacy receipt replay"},"proofHash":{"type":"string","pattern":"^[a-f0-9]{64}$"},"proofCodeCommitment":{"type":"string","pattern":"^[a-f0-9]{64}$","description":"SHA-256 of agenttx-proof-code:<proofCode>; omitted only for legacy receipts"},"completedAt":{"type":"string","format":"date-time"},"counted":{"type":"boolean"},"evidenceUrl":{"type":"string","format":"uri"},"sandbox":{"const":true}}},"HumanProof":{"type":"object","required":["sessionCommitment","completedAt","outcomes","counted","proofHash"],"properties":{"sessionCommitment":{"type":"string","pattern":"^[a-f0-9]{64}$"},"completedAt":{"type":"string","format":"date-time"},"outcomes":{"type":"array","items":{"enum":["ALLOW","REQUIRE_APPROVAL","DENY"]}},"counted":{"const":true},"proofHash":{"type":"string","pattern":"^[a-f0-9]{64}$"},"proofCodeCommitment":{"type":"string","pattern":"^[a-f0-9]{64}$","description":"Commitment that links a private completion code to this public proof; omitted for legacy proofs"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","requestId"],"properties":{"code":{"type":"string"},"requestId":{"type":"string","format":"uuid"}}}}}}}}