{"openapi":"3.1.0","jsonSchemaDialect":"https://json-schema.org/draft/2020-12/schema","info":{"title":"VouchSpec Agent Skill Evidence API","version":"0.1.0","description":"Agent-only API for purchasing fresh, isolated static validation and signed evidence for one exact immutable public GitHub Agent Skill commit. There is no human checkout.","termsOfService":"https://vouchspec.plyrium.com/vouchspec/policies"},"externalDocs":{"description":"VouchSpec machine discovery contract","url":"https://vouchspec.plyrium.com/api/vouchspec/v1/discovery"},"servers":[{"url":"https://vouchspec.plyrium.com","description":"Base mainnet commerce"}],"tags":[{"name":"Discovery","description":"Free, anonymous machine-readable service metadata."},{"name":"Purchase","description":"x402-paid exact-commit validation intake."},{"name":"Verification","description":"Public receipt bytes, status, and issuer key."}],"x-vouchspec":{"agentOnly":true,"humanCheckout":false,"profile":"vouchspec-public-static-v1","operation":"fresh_public_static_validation","payment":{"protocol":"x402","version":2,"scheme":"exact","network":"eip155:8453","asset":"USDC","amount":"0.25","atomicAmount":"250000"},"ardCatalog":"https://vouchspec.plyrium.com/.well-known/ai-catalog.json","fulfillment":{"accepted_input":"immutable_public_github_coordinates","artifact_uploads":false,"private_repositories":false,"artifact_code_executed":false,"inspection_worker_egress":false,"signer_egress":false,"expected_delivery_minutes":10}},"paths":{"/api/vouchspec/v1/health":{"get":{"tags":["Discovery"],"operationId":"getVouchSpecHealth","summary":"Check whether commerce is operational","responses":{"200":{"description":"VouchSpec is operational.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/api/vouchspec/v1/discovery":{"get":{"tags":["Discovery"],"operationId":"getVouchSpecDiscovery","summary":"Get the canonical VouchSpec machine contract","responses":{"200":{"description":"Current endpoints, schemas, payment terms, and receipt rules.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/.well-known/x402":{"get":{"tags":["Discovery"],"operationId":"getVouchSpecX402Manifest","summary":"Get the x402 payment manifest","responses":{"200":{"description":"Current x402 endpoint and payment requirement metadata.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/api/vouchspec/v1/validate":{"post":{"tags":["Purchase"],"operationId":"purchaseExactCommitValidation","summary":"Purchase validation for one exact public Agent Skill commit","description":"Send the strict validation request without PAYMENT-SIGNATURE to receive the canonical 402 challenge. Authorize exactly that challenge, then retry the identical request with PAYMENT-SIGNATURE. An exactly empty unpaid probe is also accepted for challenge discovery; a paid request always requires the body.","parameters":[{"$ref":"#/components/parameters/PaymentSignature"}],"requestBody":{"required":false,"description":"Required for every purchase and payment retry; optional only for an empty unpaid challenge probe.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationRequest"}}}},"responses":{"200":{"description":"Payment settled. One-time bearer credentials and delivery endpoints are returned.","headers":{"PAYMENT-RESPONSE":{"description":"Base64-encoded x402 settlement response.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaidValidationAccess"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"402":{"description":"Payment is required. Authorize the exact challenge and retry the identical request.","headers":{"PAYMENT-REQUIRED":{"description":"Base64-encoded x402 v2 payment requirements.","required":true,"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"$ref":"#/components/responses/Forbidden"},"413":{"$ref":"#/components/responses/TooLarge"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}},"x-x402":{"version":2,"scheme":"exact","network":"eip155:8453","asset":"USDC","amountAtomic":"250000","manifest":"https://vouchspec.plyrium.com/.well-known/x402"},"x-vouchspec-side-effects":"Payment settlement and asynchronous isolated validation after a valid paid retry."}},"/api/vouchspec/v1/keys/issuer":{"get":{"tags":["Verification"],"operationId":"getVouchSpecIssuerKey","summary":"Get the current Ed25519 receipt-verification key","responses":{"200":{"description":"Public issuer key and key identifier.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IssuerKey"}}}},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/api/vouchspec/v1/receipts/{sha256_hex}":{"get":{"tags":["Verification"],"operationId":"getVouchSpecReceipt","summary":"Fetch immutable DSSE receipt bytes by SHA-256 digest","parameters":[{"$ref":"#/components/parameters/Sha256Hex"}],"responses":{"200":{"description":"Exact immutable DSSE envelope bytes.","content":{"application/vnd.dsse.envelope.v1+json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"$ref":"#/components/responses/NotFound"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/api/vouchspec/v1/receipts/{sha256_hex}/status":{"get":{"tags":["Verification"],"operationId":"getVouchSpecReceiptStatus","summary":"Check the live reliance status for a receipt","description":"Fetch this no-store status before every new reliance decision; cached receipt bytes alone are insufficient.","parameters":[{"$ref":"#/components/parameters/Sha256Hex"}],"responses":{"200":{"description":"Current receipt lifecycle status.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"$ref":"#/components/responses/NotFound"},"503":{"$ref":"#/components/responses/Unavailable"}}}}},"components":{"parameters":{"PaymentSignature":{"name":"PAYMENT-SIGNATURE","in":"header","required":false,"description":"Base64-encoded x402 v2 authorization supplied only on the paid retry.","schema":{"type":"string","maxLength":16384}},"Sha256Hex":{"name":"sha256_hex","in":"path","required":true,"description":"Lowercase SHA-256 digest of the exact DSSE envelope bytes, without the sha256: prefix.","schema":{"type":"string","pattern":"^[0-9a-f]{64}$"}}},"schemas":{"ValidationRequest":{"type":"object","additionalProperties":false,"required":["schema_version","operation","source","profile","max_price","delivery_id"],"properties":{"schema_version":{"const":"1.0.0"},"operation":{"const":"fresh_public_static_validation"},"source":{"type":"object","additionalProperties":false,"required":["host","owner","repository","commit","skill_path"],"properties":{"host":{"const":"github.com"},"owner":{"type":"string","pattern":"^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$"},"repository":{"type":"string","pattern":"^[A-Za-z0-9](?:[A-Za-z0-9_.-]{0,99})$"},"commit":{"type":"string","pattern":"^[0-9a-f]{40}$"},"skill_path":{"type":"string","minLength":1,"maxLength":1024}}},"profile":{"const":"vouchspec-public-static-v1"},"max_price":{"type":"object","additionalProperties":false,"required":["currency","amount_minor"],"properties":{"currency":{"const":"usd"},"amount_minor":{"type":"integer","minimum":25,"maximum":1000000}}},"delivery_id":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,64}$"}}},"PaidValidationAccess":{"type":"object","additionalProperties":false,"required":["schema_version","order","credentials","endpoints","payment"],"properties":{"schema_version":{"const":"1.0.0"},"order":{"type":"object","additionalProperties":true},"credentials":{"type":"object","additionalProperties":false,"required":["tenant_api_key","delivery_token","delivery_token_expires_at","notice"],"properties":{"tenant_api_key":{"type":"string","description":"Secret bearer capability shown once."},"delivery_token":{"type":"string","description":"Secret delivery capability shown once."},"delivery_token_expires_at":{"type":"string","format":"date-time"},"notice":{"type":"string"}}},"endpoints":{"type":"object","additionalProperties":true},"payment":{"type":"object","additionalProperties":true}}},"IssuerKey":{"type":"object","additionalProperties":false,"required":["schema_version","key_id","algorithm","public_key_jwk","use"],"properties":{"schema_version":{"const":"1.0"},"key_id":{"type":"string"},"algorithm":{"const":"Ed25519"},"public_key_jwk":{"type":"object","additionalProperties":true},"use":{"type":"string"}}},"Error":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}},"responses":{"BadRequest":{"description":"Malformed or invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"Cross-site mutation rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"TooLarge":{"description":"Request body exceeds the bounded intake limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Request rate exceeded.","headers":{"Retry-After":{"schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"VouchSpec is temporarily unavailable.","headers":{"Retry-After":{"schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}