{"openapi":"3.1.0","info":{"title":"Telaro Procurement API","version":"1.0.0","description":"Private organization-scoped control plane. Financial mutations are idempotent and return explicit financialState metadata on errors."},"servers":[{"url":"/","description":"Current procurement service"}],"security":[{"bearerAuth":[]}],"paths":{"/health":{"get":{"operationId":"getProcurementHealth","security":[],"responses":{"200":{"description":"Storage-backed service health"}}}},"/api/v1/schema":{"get":{"operationId":"getProcurementSchema","security":[],"responses":{"200":{"description":"Public-safe capability flags"}}}},"/api/v1/openapi.json":{"get":{"operationId":"getProcurementOpenApi","security":[],"responses":{"200":{"description":"This OpenAPI contract"}}}},"/api/v1/auth/challenges":{"post":{"operationId":"createProcurementAuthChallenge","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["wallet"],"properties":{"wallet":{"type":"string"}}}}}},"responses":{"201":{"description":"Exact wallet challenge message"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/auth/sessions":{"post":{"operationId":"createProcurementSession","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["challengeId","wallet","signature"],"properties":{"challengeId":{"type":"string"},"wallet":{"type":"string"},"signature":{"type":"string"}}}}}},"responses":{"201":{"description":"Organization membership session"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/auth/sessions/current/refresh":{"post":{"operationId":"refreshProcurementSession","description":"Atomically rotates the current bearer token and extends its bounded expiry.","responses":{"200":{"description":"Rotated organization membership session"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/auth/sessions/current":{"delete":{"operationId":"revokeProcurementSession","description":"Revokes the current bearer session. The response is idempotent.","responses":{"200":{"description":"Session revoked or already inactive"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/organizations":{"get":{"operationId":"listProcurementOrganizations","responses":{"200":{"description":"Organizations available to the authenticated actor"},"default":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"createProcurementOrganization","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrganizationInput"}}}},"responses":{"201":{"description":"Atomically provisioned organization control plane"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/organization/setup":{"get":{"operationId":"getProcurementOrganizationSetup","parameters":[{"$ref":"#/components/parameters/OrganizationId"}],"responses":{"200":{"description":"Tenant-scoped workspace, policy and budget configuration"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/organization/members":{"get":{"operationId":"listProcurementOrganizationMembers","parameters":[{"$ref":"#/components/parameters/OrganizationId"}],"responses":{"200":{"description":"Owner/Admin view of organization members and access state","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/OrganizationMember"}}}}},"default":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"addProcurementOrganizationMember","parameters":[{"$ref":"#/components/parameters/OrganizationId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["actorId","role"],"properties":{"actorId":{"type":"string","description":"Exact Solana wallet address"},"role":{"$ref":"#/components/schemas/OrganizationRole"}}}}}},"responses":{"201":{"description":"Active wallet-backed organization membership","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationMember"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/organization/members/{actorId}":{"post":{"operationId":"updateProcurementOrganizationMember","parameters":[{"$ref":"#/components/parameters/OrganizationId"},{"$ref":"#/components/parameters/IdempotencyKey"},{"name":"actorId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","minProperties":1,"properties":{"role":{"$ref":"#/components/schemas/OrganizationRole"},"status":{"type":"string","enum":["active","revoked"]}}}}}},"responses":{"200":{"description":"Updated membership with last-Owner protection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationMember"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/procurement/requests":{"post":{"operationId":"createProcurementRequest","parameters":[{"$ref":"#/components/parameters/OrganizationId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"201":{"description":"Created procurement request"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/procurement/assist/interpret":{"post":{"operationId":"interpretProcurementRequest","description":"Creates an editable Gemini draft. It never creates a request or authorizes funds.","parameters":[{"$ref":"#/components/parameters/OrganizationId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InterpretRequestInput"}}}},"responses":{"200":{"description":"Human-reviewable procurement request draft"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/procurement/approvals":{"get":{"operationId":"listPendingProcurementApprovals","parameters":[{"$ref":"#/components/parameters/OrganizationId"},{"name":"workspaceId","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Pending executions with immutable approval subjects"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/procurement/executions":{"get":{"operationId":"listProcurementExecutions","parameters":[{"$ref":"#/components/parameters/OrganizationId"},{"name":"workspaceId","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string","enum":["approval_pending","authorized","reserved","create_pending","funding_pending","funded","submitted","verified","verification_failed","dispute_pending","dispute_unknown","disputed","reclaim_pending","reclaim_unknown","verdict_unknown","accept_pending","acceptance_unknown","settled","recovered","payment_unknown","failed","denied","cancelled"]}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Cursor-paginated protected executions"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/procurement/receipts":{"get":{"operationId":"listProcurementReceipts","parameters":[{"$ref":"#/components/parameters/OrganizationId"},{"name":"workspaceId","in":"query","schema":{"type":"string"}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Cursor-paginated settlement receipts"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/procurement/providers":{"get":{"operationId":"listProcurementProviders","parameters":[{"$ref":"#/components/parameters/OrganizationId"},{"name":"workspaceId","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Organization provider history with latest frozen trust evidence"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/procurement/audit-events":{"get":{"operationId":"listProcurementAuditEvents","parameters":[{"$ref":"#/components/parameters/OrganizationId"},{"name":"workspaceId","in":"query","schema":{"type":"string"}},{"name":"runId","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Authoritative tenant audit ledger"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/procurement/requests/{requestId}":{"get":{"operationId":"getProcurementRequest","parameters":[{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/OrganizationId"}],"responses":{"200":{"description":"Procurement request"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/procurement/requests/{requestId}/evaluate-policy":{"post":{"operationId":"evaluateProcurementPolicy","parameters":[{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/OrganizationId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"Fail-closed policy decision"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/procurement/requests/{requestId}/discover-candidates":{"post":{"operationId":"discoverProcurementCandidates","parameters":[{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/OrganizationId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"201":{"description":"At most three policy-eligible candidates"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/procurement/requests/{requestId}/candidates/latest":{"get":{"operationId":"getLatestProcurementCandidates","parameters":[{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/OrganizationId"}],"responses":{"200":{"description":"Latest candidate comparison"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/procurement/requests/{requestId}/recommend-candidates":{"post":{"operationId":"recommendProcurementCandidates","description":"Explains and orders only candidates from a persisted policy-eligible discovery.","parameters":[{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/OrganizationId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["discoveryId"],"properties":{"discoveryId":{"type":"string"}}}}}},"responses":{"200":{"description":"Advisory candidate recommendation"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/procurement/requests/{requestId}/executions":{"post":{"operationId":"prepareSacpExecution","parameters":[{"$ref":"#/components/parameters/RequestId"},{"$ref":"#/components/parameters/OrganizationId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"201":{"description":"Immutable protected execution"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/procurement/executions/{executionId}":{"get":{"operationId":"getProcurementExecution","parameters":[{"$ref":"#/components/parameters/ExecutionId"},{"$ref":"#/components/parameters/OrganizationId"}],"responses":{"200":{"description":"Current protected execution state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProcurementExecution"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/procurement/executions/{executionId}/approvals":{"post":{"operationId":"decideProcurementApproval","parameters":[{"$ref":"#/components/parameters/ExecutionId"},{"$ref":"#/components/parameters/OrganizationId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Current protected execution state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProcurementExecution"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/procurement/executions/{executionId}/execute":{"post":{"operationId":"executeSacp","parameters":[{"$ref":"#/components/parameters/ExecutionId"},{"$ref":"#/components/parameters/OrganizationId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"Current protected execution state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProcurementExecution"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/procurement/executions/{executionId}/sync-submission":{"post":{"operationId":"syncSacpSubmission","parameters":[{"$ref":"#/components/parameters/ExecutionId"},{"$ref":"#/components/parameters/OrganizationId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"Current protected execution state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProcurementExecution"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/procurement/executions/{executionId}/verify":{"post":{"operationId":"verifyProcurementSubmission","parameters":[{"$ref":"#/components/parameters/ExecutionId"},{"$ref":"#/components/parameters/OrganizationId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerificationInput"}}}},"responses":{"200":{"description":"Current protected execution state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProcurementExecution"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/procurement/executions/{executionId}/accept":{"post":{"operationId":"acceptSacpSubmission","parameters":[{"$ref":"#/components/parameters/ExecutionId"},{"$ref":"#/components/parameters/OrganizationId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"Current protected execution state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProcurementExecution"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/procurement/executions/{executionId}/dispute":{"post":{"operationId":"disputeSacpSubmission","parameters":[{"$ref":"#/components/parameters/ExecutionId"},{"$ref":"#/components/parameters/OrganizationId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DisputeInput"}}}},"responses":{"200":{"description":"Current protected execution state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProcurementExecution"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/procurement/executions/{executionId}/reclaim":{"post":{"operationId":"reclaimSacpEscrow","parameters":[{"$ref":"#/components/parameters/ExecutionId"},{"$ref":"#/components/parameters/OrganizationId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"Current protected execution state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProcurementExecution"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/procurement/executions/{executionId}/sync-verdict":{"post":{"operationId":"syncSacpVerdict","parameters":[{"$ref":"#/components/parameters/ExecutionId"},{"$ref":"#/components/parameters/OrganizationId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"Current protected execution state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProcurementExecution"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/procurement/runs":{"get":{"operationId":"listProcurementRuns","parameters":[{"$ref":"#/components/parameters/OrganizationId"},{"name":"workspaceId","in":"query","schema":{"type":"string"}},{"name":"state","in":"query","schema":{"type":"string","enum":["draft","policy_review","approval_pending","authorized","discovering","trialing","provider_selected","contracting","funded","executing","verifying","settlement_pending","disputed","rejected","cancelled","failed","recovered","settled"]}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Cursor-paginated procurement runs"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/procurement/runs/{runId}":{"get":{"operationId":"getProcurementRun","parameters":[{"$ref":"#/components/parameters/RunId"},{"$ref":"#/components/parameters/OrganizationId"}],"responses":{"200":{"description":"Procurement run"},"default":{"$ref":"#/components/responses/Error"}}}},"/api/v1/procurement/runs/{runId}/receipt":{"get":{"operationId":"getProcurementReceipt","parameters":[{"$ref":"#/components/parameters/RunId"},{"$ref":"#/components/parameters/OrganizationId"}],"responses":{"200":{"description":"Private organization settlement receipt","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProcurementReceipt"}}}},"default":{"$ref":"#/components/responses/Error"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"parameters":{"OrganizationId":{"name":"x-organization-id","in":"header","required":true,"schema":{"type":"string"}},"IdempotencyKey":{"name":"idempotency-key","in":"header","required":true,"schema":{"type":"string","maxLength":200}},"RequestId":{"name":"requestId","in":"path","required":true,"schema":{"type":"string"}},"ExecutionId":{"name":"executionId","in":"path","required":true,"schema":{"type":"string"}},"RunId":{"name":"runId","in":"path","required":true,"schema":{"type":"string"}}},"responses":{"Error":{"description":"Structured procurement error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"schemas":{"OrganizationRole":{"type":"string","enum":["owner","admin","approver","requester","finance","auditor"]},"OrganizationMember":{"type":"object","required":["organizationId","actorId","role","status","createdAt","updatedAt"],"properties":{"organizationId":{"type":"string"},"actorId":{"type":"string"},"role":{"$ref":"#/components/schemas/OrganizationRole"},"status":{"type":"string","enum":["invited","active","revoked"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"CreateOrganizationInput":{"type":"object","required":["organization","workspace","costCenter","settlement","limits","policy"],"properties":{"organization":{"type":"object"},"workspace":{"type":"object"},"costCenter":{"type":"object"},"settlement":{"type":"object"},"limits":{"type":"object","description":"Explicit bounded atomic-string limits; unbounded bootstrap is not supported."},"policy":{"type":"object"}}},"InterpretRequestInput":{"type":"object","required":["prompt","currentDraft"],"properties":{"prompt":{"type":"string","minLength":1,"maxLength":4000},"locale":{"type":"string","enum":["en","ko"]},"currentDraft":{"type":"object","required":["maximumSpendUsd","deadline","dataClass","acceptanceMethod"],"properties":{"maximumSpendUsd":{"type":"string"},"deadline":{"type":"string","format":"date"},"dataClass":{"type":"string","enum":["public","internal","confidential"]},"acceptanceMethod":{"type":"string","enum":["human","deterministic"]},"category":{"type":"integer","minimum":0,"maximum":255}}}}},"ErrorEnvelope":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","retryable","financialState","requestId"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"},"financialState":{"type":"string","enum":["no_authorization","reserved","payment_unknown","funded","settled","recovered"]},"requestId":{"type":"string"}}}}},"ProcurementExecution":{"type":"object","required":["id","runId","requestId","organizationId","workspaceId","rail","status"],"properties":{"id":{"type":"string"},"runId":{"type":"string"},"requestId":{"type":"string"},"organizationId":{"type":"string"},"workspaceId":{"type":"string"},"rail":{"const":"sacp"},"status":{"type":"string","enum":["approval_pending","authorized","reserved","create_pending","funding_pending","funded","submitted","verified","verification_failed","dispute_pending","dispute_unknown","disputed","reclaim_pending","reclaim_unknown","verdict_unknown","accept_pending","acceptance_unknown","settled","recovered","payment_unknown","failed","denied","cancelled"]},"submission":{"type":"object"},"verification":{"type":"object"},"receiptId":{"type":"string"}},"additionalProperties":true},"VerificationInput":{"type":"object","properties":{"outcome":{"type":"string","enum":["passed","failed","inconclusive"]},"reason":{"type":"string","minLength":1,"maxLength":1000},"evidence":{"type":"array","maxItems":20,"items":{"type":"object"}}},"description":"Human verification accepts an explicit outcome. Deterministic verification requires an empty object and uses the configured server verifier."},"DisputeInput":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string","minLength":1,"maxLength":4000},"evidence":{"type":"array","maxItems":20,"items":{"type":"object"}},"evidenceUri":{"type":"string","maxLength":256}},"description":"Private dispute rationale. The control plane freezes the record and writes only its SHA-256 digest to sACP."},"ProcurementReceipt":{"type":"object","required":["schema","runId","requestRef","provider","settlement","auditRoot","createdAt"],"properties":{"schema":{"const":"telaro-procurement-receipt/v1"},"runId":{"type":"string"},"requestRef":{"type":"string"},"provider":{"type":"string"},"verification":{"type":"object"},"settlement":{"type":"object"},"auditRoot":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}},"additionalProperties":true}}}}