{"openapi":"3.1.0","info":{"title":"Stackbroker API","version":"0.1.0-proof-slice","description":"Live proof-slice API for Stackbroker service discovery, routing, service-card lookup, audit lookup, probe ingest, and outcome telemetry. Schemas mirror lib/schema contract version 2026-06-01."},"servers":[{"url":"https://api.stackbroker.xyz"}],"paths":{"/v1/discover":{"get":{"summary":"Discover candidate agent-callable services","operationId":"discoverServices","parameters":[{"name":"capability","in":"query","required":true,"schema":{"type":"string","minLength":1}},{"name":"max_price_usdc","in":"query","required":false,"schema":{"type":"number","minimum":0}},{"name":"max_latency_ms","in":"query","required":false,"schema":{"type":"integer","minimum":1}},{"name":"payment_rail","in":"query","required":false,"schema":{"$ref":"#/components/schemas/PaymentRail"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":10}},{"name":"source","in":"query","required":false,"description":"Provenance source filter (e.g. curated_seed, x402_bazaar)","schema":{"type":"string"}},{"name":"min_attestation_tier","in":"query","required":false,"schema":{"type":"string","enum":["seed","probed","verified","attested"]}},{"name":"scanned_within_days","in":"query","required":false,"description":"Only candidates with a trust scan within N days","schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Candidate service-card summaries","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DiscoverResponse"}}}},"400":{"description":"Invalid query"}}}},"/v1/services/{id}":{"get":{"summary":"Fetch a normalized service card","operationId":"getService","parameters":[{"name":"id","in":"path","required":true,"description":"Service-card service_id","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Service card","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceCard"}}}},"404":{"description":"Service not found"}}}},"/v1/route":{"post":{"summary":"Route a request to a ranked seller candidate","operationId":"routeRequest","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouteRequest"}}}},"responses":{"200":{"description":"Route result with selected service, rationale, fallbacks, policy result, and audit ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouteResponse"}}}},"400":{"description":"Invalid JSON or route request"}}}},"/v1/preflight":{"post":{"summary":"Evaluate governance policy before a route or irreversible spend","operationId":"preflightRoute","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreflightRequest"}}}},"responses":{"200":{"description":"Preflight decision with policy checks, route proof preview, and net-cost delta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreflightResponse"}}}},"400":{"description":"Invalid JSON or preflight request"}}}},"/v1/governance/events":{"get":{"summary":"Read recent org-scoped governance proof and policy events","operationId":"listGovernanceEvents","description":"Requires an organization API key. Anonymous callers cannot read proof streams.","responses":{"200":{"description":"Recent route proofs, policy events, and listed service-state events scoped to the caller organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GovernanceStream"}}}},"401":{"description":"Organization API key required"},"503":{"description":"Governance store not provisioned"}}}},"/v1/audits/{id}":{"get":{"summary":"Fetch the evidence trail behind a routing decision","operationId":"getAudit","parameters":[{"name":"id","in":"path","required":true,"description":"Route audit_id","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Audit event plus an additive `replay` block: methodology_version, scoring_version, proof_hash, policy_checks, and the audit-chain link (seq, record_hash, prev_hash) for independent verification","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditEvent"}}}},"404":{"description":"Audit not found"},"503":{"description":"Audit store not provisioned"}}}},"/v1/audits/anchors":{"get":{"summary":"Public daily Ed25519-signed anchors over the audit hash chain","operationId":"listAuditAnchors","description":"Anchors carry hashes and counts only. Verify each anchor's base64 signature over canonical JSON (recursively key-sorted) of its payload against /.well-known/stackbroker-signing-key. Walkthrough: https://stackbroker.xyz/audit","responses":{"200":{"description":"Chain rules, signing key reference, and recent anchors"}}}},"/v1/methodology":{"get":{"summary":"Machine-readable scoring methodology and neutrality invariants","operationId":"getMethodology","description":"The same versioned config the production scoring engine runs on (CI drift-tested): factors, weights, evidence-null treatment, attestation ladder, risk-flag semantics, NOT-factors, and both neutrality invariants (providers never pay; subscriptions buy access, never outcomes).","responses":{"200":{"description":"Current methodology version, factors, weights, effective date, invariants, changelog"}}}},"/v1/services/{id}/trust":{"get":{"summary":"Active signed trust manifest for a service","operationId":"getTrustManifest","description":"Point-in-time trust evidence (Ed25519-signed): static description/schema analysis, schema drift, endpoint reputation — mapped through a versioned rubric. No runtime traffic inspection; stale manifests are served marked stale. Scope: https://stackbroker.xyz/trust","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Signed manifest, signature, key_id, verification rule"},"404":{"description":"No trust manifest exists for this service yet"}}}},"/v1/services/{id}/trust/rescan":{"post":{"summary":"Request a free re-scan (provider connection token or org API key)","operationId":"requestTrustRescan","description":"Free for providers after remediation (connection-point token) and available to keyed operators routing to the service. Rate limits are access controls only — scan content and rubric are identical regardless of who asks.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"connection_address":{"type":"string"},"connection_token":{"type":"string"}}}}}},"responses":{"202":{"description":"Re-scan queued"},"401":{"description":"Authentication required"},"429":{"description":"Re-scan already requested in the last 24h"}}}},"/v1/sellers/connection":{"post":{"summary":"Register a provider connection point (free)","operationId":"registerConnectionPoint","description":"The free contact channel that, with the claimed card, is the only requirement for full verification benefits. Email addresses must be at the service's domain; a confirmation link verifies control.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["service_id","address"],"properties":{"service_id":{"type":"string"},"kind":{"type":"string","enum":["email","webhook"],"default":"email"},"address":{"type":"string"}}}}}},"responses":{"202":{"description":"Connection point registered; confirmation pending"}}},"get":{"summary":"Confirm a provider connection point","operationId":"confirmConnectionPoint","parameters":[{"name":"service_id","in":"query","required":true,"schema":{"type":"string"}},{"name":"address","in":"query","required":true,"schema":{"type":"string"}},{"name":"token","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Connection point verified"},"401":{"description":"Token mismatch"}}}},"/v1/outcomes":{"post":{"summary":"Submit structured outcome telemetry","operationId":"submitOutcome","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutcomeRecord"}}}},"responses":{"201":{"description":"Outcome persisted"},"202":{"description":"Outcome accepted for validation but telemetry storage is not provisioned"},"400":{"description":"Invalid JSON or outcome record"},"500":{"description":"Persistence error"}}}},"/v1/probes/results":{"post":{"summary":"Internal/admin probe-result ingest","operationId":"submitProbeResults","description":"Accepts a single ProbeResult or an array of ProbeResult objects. Requires Bearer PROBE_ADMIN_TOKEN.","security":[{"probeAdminToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProbeResult"},{"type":"array","items":{"$ref":"#/components/schemas/ProbeResult"}}]}}}},"responses":{"201":{"description":"Probe result recorded"},"202":{"description":"Probe result accepted but probe store is not provisioned"},"400":{"description":"Invalid JSON or probe result"},"401":{"description":"Unauthorized"},"500":{"description":"Persistence error"}}}}},"components":{"securitySchemes":{"probeAdminToken":{"type":"http","scheme":"bearer","description":"Internal/admin PROBE_ADMIN_TOKEN bearer credential."}},"schemas":{"PaymentRail":{"type":"string","enum":["x402","api_key","oauth","stripe","circle","fireblocks","connector","free"]},"PolicyFlag":{"type":"string","enum":["browser_control","external_network","stores_data","pii_processing","code_execution","financial_action"]},"AttestationTier":{"type":"string","enum":["seed","probed","verified","attested"]},"RoutePolicyResult":{"type":"string","enum":["pass","filtered_all","partial"]},"ServiceCardSummary":{"type":"object","required":["service_id","name","provider","capabilities","payment_rails","price_usdc_estimate","attestation_tier","p95_latency_ms","success_rate"],"properties":{"service_id":{"type":"string"},"name":{"type":"string"},"provider":{"type":"string"},"capabilities":{"type":"array","items":{"type":"string"}},"payment_rails":{"type":"array","items":{"$ref":"#/components/schemas/PaymentRail"}},"price_usdc_estimate":{"type":["number","null"],"minimum":0},"attestation_tier":{"$ref":"#/components/schemas/AttestationTier"},"p95_latency_ms":{"type":["number","null"],"minimum":0},"success_rate":{"type":["number","null"],"minimum":0,"maximum":1}}},"ServiceCard":{"allOf":[{"$ref":"#/components/schemas/ServiceCardSummary"},{"type":"object","required":["mcp_available","api_available","price_unit","auth_owner","payment_owner","receipt_issuer","schema_version","p50_latency_ms","schema_conformance_rate","idempotency","replay_safety","refund_path","policy_flags","last_probe_at"],"properties":{"endpoint_url":{"type":"string","format":"uri"},"mcp_available":{"type":"boolean","default":false},"api_available":{"type":"boolean","default":true},"price_unit":{"type":"string","enum":["per_call","per_token","per_minute","per_task","subscription","free"]},"auth_owner":{"type":"string","enum":["provider","stackbroker","operator"],"default":"provider"},"payment_owner":{"type":"string","enum":["provider","stackbroker","operator"],"default":"provider"},"receipt_issuer":{"type":"string","enum":["provider","stackbroker","none"],"default":"provider"},"schema_version":{"type":"string"},"p50_latency_ms":{"type":["number","null"],"minimum":0},"schema_conformance_rate":{"type":["number","null"],"minimum":0,"maximum":1},"idempotency":{"type":"string","enum":["yes","no","unknown"],"default":"unknown"},"replay_safety":{"type":"string","enum":["yes","no","unknown"],"default":"unknown"},"refund_path":{"type":"string","default":"provider_policy"},"policy_flags":{"type":"array","items":{"$ref":"#/components/schemas/PolicyFlag"},"default":[]},"last_probe_at":{"type":["string","null"],"format":"date-time"}}}]},"DiscoverResponse":{"type":"object","required":["capability","count","candidates"],"properties":{"capability":{"type":"string"},"count":{"type":"integer","minimum":0},"candidates":{"type":"array","items":{"$ref":"#/components/schemas/ServiceCardSummary"}}}},"RoutePolicy":{"type":"object","properties":{"max_price_usdc":{"type":"number","minimum":0},"max_latency_ms":{"type":"integer","minimum":1},"allowed_payment_rails":{"type":"array","items":{"$ref":"#/components/schemas/PaymentRail"}},"blocked_policy_flags":{"type":"array","items":{"$ref":"#/components/schemas/PolicyFlag"}},"require_attestation_tier":{"type":"string","enum":["seed","probed","verified","attested"]}}},"RouteRequest":{"type":"object","required":["task","capability"],"properties":{"task":{"type":"string","minLength":1},"capability":{"type":"string","minLength":1},"policy":{"$ref":"#/components/schemas/RoutePolicy","default":{}},"agent_id":{"type":"string"}}},"GovernanceContext":{"type":"object","properties":{"policy_profile_id":{"type":"string"},"policy_version":{"type":"string","default":"adhoc"},"expected_spend_usdc":{"type":["number","null"],"minimum":0},"approved_spend_usdc":{"type":["number","null"],"minimum":0},"rebate_usdc":{"type":["number","null"],"minimum":0},"previous_service_id":{"type":"string"},"blocked_services":{"type":"array","items":{"type":"string"},"default":[]},"require_confirmation_above_usdc":{"type":["number","null"],"minimum":0},"operator_burst_window":{"type":"boolean","default":false},"anomaly_spend_multiplier":{"type":"number","minimum":0,"exclusiveMinimum":true,"default":2}}},"PreflightRequest":{"allOf":[{"$ref":"#/components/schemas/RouteRequest"},{"type":"object","properties":{"governance":{"$ref":"#/components/schemas/GovernanceContext","default":{}}}}]},"RouteCandidate":{"type":"object","required":["service_id","score","why_selected","risk_flags","expected_price_usdc"],"properties":{"service_id":{"type":"string"},"score":{"type":"number","minimum":0,"maximum":100},"why_selected":{"type":"array","items":{"type":"string"}},"risk_flags":{"type":"array","items":{"type":"string"},"default":[]},"expected_price_usdc":{"type":["number","null"],"minimum":0}}},"RouteResponse":{"type":"object","required":["selected_service","score","why_selected","second_choice","risk_flags","fallback_options","policy_result","audit_id"],"properties":{"selected_service":{"type":["string","null"]},"score":{"type":["number","null"],"minimum":0,"maximum":100},"why_selected":{"type":"array","items":{"type":"string"}},"second_choice":{"type":["string","null"]},"risk_flags":{"type":"array","items":{"type":"string"}},"fallback_options":{"type":"array","items":{"$ref":"#/components/schemas/RouteCandidate"}},"policy_result":{"$ref":"#/components/schemas/RoutePolicyResult"},"audit_id":{"type":"string"}}},"PolicyCheck":{"type":"object","required":["code","status","message"],"properties":{"code":{"type":"string"},"status":{"type":"string","enum":["pass","needs_confirmation","blocked"]},"message":{"type":"string"}}},"RouteProofPreview":{"type":"object","required":["audit_id","proof_hash","policy_version","selected_service","decision","net_cost_delta_usdc","generated_at"],"properties":{"audit_id":{"type":"string"},"proof_hash":{"type":"string"},"policy_version":{"type":"string"},"selected_service":{"type":["string","null"]},"decision":{"type":"string","enum":["go","needs_confirmation","blocked"]},"net_cost_delta_usdc":{"type":["number","null"]},"generated_at":{"type":"string","format":"date-time"}}},"PreflightResponse":{"type":"object","required":["decision","selected_service","second_choice","policy_result","policy_checks","service_state_refs","proof_preview","net_cost_delta_usdc","anomaly_flags","context_shift_flags","candidates"],"properties":{"decision":{"type":"string","enum":["go","needs_confirmation","blocked"]},"selected_service":{"type":["string","null"]},"second_choice":{"type":["string","null"]},"policy_result":{"$ref":"#/components/schemas/RoutePolicyResult"},"policy_checks":{"type":"array","items":{"$ref":"#/components/schemas/PolicyCheck"}},"service_state_refs":{"type":"array","items":{"type":"string"}},"proof_preview":{"$ref":"#/components/schemas/RouteProofPreview"},"net_cost_delta_usdc":{"type":["number","null"]},"anomaly_flags":{"type":"array","items":{"type":"string"}},"context_shift_flags":{"type":"array","items":{"type":"string"}},"candidates":{"type":"array","items":{"$ref":"#/components/schemas/RouteCandidate"}}}},"GovernanceStream":{"type":"object","required":["proofs","policy_events","service_state_events"],"properties":{"proofs":{"type":"array","items":{"type":"object","additionalProperties":true}},"policy_events":{"type":"array","items":{"type":"object","additionalProperties":true}},"service_state_events":{"type":"array","items":{"type":"object","additionalProperties":true}}}},"AuditEvent":{"type":"object","required":["audit_id","created_at","agent_id","organization_id","capability","task","policy_snapshot","candidates_considered","selected_service","policy_result","scoring_version"],"properties":{"audit_id":{"type":"string","minLength":1},"created_at":{"type":"string","format":"date-time"},"agent_id":{"type":["string","null"]},"organization_id":{"type":["string","null"]},"capability":{"type":"string"},"task":{"type":"string"},"policy_snapshot":{"type":"object","additionalProperties":true},"candidates_considered":{"type":"array","items":{"$ref":"#/components/schemas/RouteCandidate"}},"selected_service":{"type":["string","null"]},"policy_result":{"$ref":"#/components/schemas/RoutePolicyResult"},"scoring_version":{"type":"string"}}},"OutcomeRecord":{"type":"object","required":["audit_id","agent_id","capability","service_id"],"properties":{"audit_id":{"type":"string","minLength":1},"agent_id":{"type":"string","minLength":1},"capability":{"type":"string","minLength":1},"service_id":{"type":"string","minLength":1},"quoted_price_usdc":{"type":["number","null"],"minimum":0,"default":null},"actual_price_usdc":{"type":["number","null"],"minimum":0,"default":null},"latency_ms":{"type":["integer","null"],"minimum":0,"default":null},"schema_conformance":{"type":"string","enum":["pass","fail","partial","unknown"],"default":"unknown"},"parse_repair_needed":{"type":"boolean","default":false},"retry_count":{"type":"integer","minimum":0,"default":0},"downstream_task_success":{"type":"string","enum":["yes","no","partial","unknown"],"default":"unknown"},"uniqueness_vs_free_sources":{"type":"string","enum":["high","medium","low","none","unknown"],"default":"unknown"},"outcome":{"type":"string","enum":["used","discarded","errored","unknown"],"default":"unknown"},"recommendation":{"type":"string","enum":["recommend","neutral","avoid"],"default":"neutral"},"operator_note":{"type":"string","maxLength":2000}}},"ProbeResult":{"type":"object","required":["service_id","capability","probe_run_id","ran_at","latency_ms","status","schema_conformance"],"properties":{"service_id":{"type":"string","minLength":1},"capability":{"type":"string","minLength":1},"probe_run_id":{"type":"string","minLength":1},"ran_at":{"type":"string","format":"date-time"},"latency_ms":{"type":"integer","minimum":0},"status":{"type":"string","enum":["ok","error","timeout","schema_fail"]},"schema_conformance":{"type":"string","enum":["pass","fail","partial"]},"retry_count":{"type":"integer","minimum":0,"default":0},"failure_class":{"type":"string","enum":["none","auth","rate_limit","schema","network","provider_5xx","timeout","other"],"default":"none"},"raw_sample_ref":{"type":"string"}}}}}}