{"components":{"schemas":{"Error":{"properties":{"error":{"type":"string"}},"type":"object"},"Proof":{"properties":{"block":{"type":"integer"},"certificate_url":{"type":"string"},"explorer_url":{"type":"string"},"hash":{"type":"string"},"id":{"type":"string"},"org_name":{"type":"string"},"registered":{"type":"boolean"},"status":{"type":"string"},"time_utc":{"type":"string"},"timestamp":{"type":"integer"},"tx":{"type":"string"}},"type":"object"}},"securitySchemes":{"bearer":{"description":"API key from /dashboard/api (yhd_...)","scheme":"bearer","type":"http"}}},"info":{"description":"Register SHA-256 document fingerprints on Base and send registered digital deliveries. Files for /proofs are never uploaded: hash locally.","title":"YHD Proof API","version":"1.0.0"},"openapi":"3.0.3","paths":{"/api/v1/credentials":{"post":{"requestBody":{"content":{"application/json":{"schema":{"properties":{"credentials":{"items":{"properties":{"email":{"type":"string"},"expiry":{"format":"date","type":"string"},"fields":{"type":"object"},"id_last4":{"type":"string"},"issue_date":{"format":"date","type":"string"},"recipient_name":{"type":"string"}},"required":["recipient_name"],"type":"object"},"maxItems":500,"type":"array"},"recipient_name":{"description":"single-credential shorthand","type":"string"},"send_email":{"type":"boolean"},"template_id":{"type":"integer"}},"required":["template_id"],"type":"object"}}},"required":true},"responses":{"201":{"description":"batch {root, tx} + items with verify_url (contains secret)"},"400":{"description":"Validation"},"429":{"description":"Cap reached"}},"security":[{"bearer":[]}],"summary":"Issue one credential or a batch (one Merkle root on Base per call, no PII on chain)"}},"/api/v1/credentials/templates":{"get":{"responses":{"200":{"description":"Templates"}},"security":[{"bearer":[]}],"summary":"List your credential templates"}},"/api/v1/credentials/verify":{"post":{"responses":{"200":{"description":"status valid|expired|revoked, merkle.ok"},"404":{"description":"Not found"}},"summary":"Public verification: {id, secret} or the holder JSON {credential, proof}, or multipart file (PDF/JSON)"}},"/api/v1/credentials/{id}":{"get":{"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Credential"},"404":{"description":"Not found"}},"security":[{"bearer":[]}],"summary":"Get a credential you issued (status, chain proof, links)"}},"/api/v1/credentials/{id}/revoke":{"post":{"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"also":{"items":{"type":"string"},"type":"array"},"reason":{"type":"string"}},"required":["reason"],"type":"object"}}},"required":true},"responses":{"200":{"description":"Revoked"},"409":{"description":"Already revoked"}},"security":[{"bearer":[]}],"summary":"Revoke (hash of the revocation list registered on Base; 'also' revokes more ids in the same tx)"}},"/api/v1/deliveries":{"post":{"requestBody":{"content":{"multipart/form-data":{"schema":{"properties":{"file":{"format":"binary","type":"string"},"message":{"type":"string"},"recipient_email":{"type":"string"},"recipient_name":{"type":"string"},"subject":{"type":"string"}},"required":["file","recipient_email","subject"],"type":"object"}}},"required":true},"responses":{"201":{"description":"Delivery created"},"400":{"description":"Validation error"},"413":{"description":"File > 10MB"},"429":{"description":"Cap reached"}},"security":[{"bearer":[]}],"summary":"Send a registered digital delivery (file is uploaded and stored privately)"}},"/api/v1/deliveries/{id}":{"get":{"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Delivery"},"404":{"description":"Not found"}},"security":[{"bearer":[]}],"summary":"Delivery status, event log, anchors, certificate URL"}},"/api/v1/ledger":{"get":{"parameters":[{"in":"query","name":"q","schema":{"type":"string"}},{"in":"query","name":"cat","schema":{"type":"string"}},{"in":"query","name":"org","schema":{"type":"string"}},{"in":"query","name":"from","schema":{"type":"string"}},{"in":"query","name":"to","schema":{"type":"string"}},{"in":"query","name":"page","schema":{"type":"string"}},{"in":"query","name":"per_page","schema":{"type":"string"}}],"responses":{"200":{"description":"Page of publications"}},"summary":"Public Ledger: list public publications (no auth)"},"post":{"requestBody":{"content":{"application/json":{"schema":{"required":["title","category","hash"],"type":"object"}},"multipart/form-data":{"schema":{"properties":{"category":{"enum":["decision","protocol","tender","budget","contract","report","other"],"type":"string"},"description":{"type":"string"},"doc_date":{"format":"date","type":"string"},"file":{"description":"Public file, max 20MB","format":"binary","type":"string"},"hash":{"description":"Hash-only publication (instead of file)","type":"string"},"prev_id":{"description":"Publish as a new version of this item","type":"integer"},"title":{"type":"string"}},"required":["title","category"],"type":"object"}}},"required":true},"responses":{"201":{"description":"Published"},"400":{"description":"Validation error"},"403":{"description":"No public profile"},"413":{"description":"File > 20MB"},"429":{"description":"Cap reached"},"503":{"description":"Paused"}},"security":[{"bearer":[]}],"summary":"Publish to the Public Ledger (file is PUBLIC, or hash-only). Org must have a public profile."}},"/api/v1/ledger/{id}":{"get":{"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Publication"},"404":{"description":"Not found"}},"summary":"One publication (no auth)"}},"/api/v1/proofs":{"get":{"parameters":[{"in":"query","name":"page","schema":{"type":"integer"}},{"in":"query","name":"per_page","schema":{"maximum":100,"type":"integer"}}],"responses":{"200":{"description":"Page of proofs"}},"security":[{"bearer":[]}],"summary":"List your org's proofs"},"post":{"requestBody":{"content":{"application/json":{"schema":{"properties":{"fname":{"type":"string"},"hash":{"example":"0xabababababababababababababababababababababababababababababababab","type":"string"},"label":{"type":"string"}},"required":["hash"],"type":"object"}}},"required":true},"responses":{"200":{"description":"Already registered"},"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Proof"}}},"description":"Registered"},"400":{"description":"Bad hash"},"401":{"description":"Bad key"},"429":{"description":"Rate limit / daily cap"},"502":{"description":"Chain error"},"503":{"description":"Paused (low balance)"}},"security":[{"bearer":[]}],"summary":"Register a document hash on Base"}},"/api/v1/proofs/{id}":{"get":{"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Proof"}}},"description":"Proof status"}},"summary":"Public verification by hash (id = hash). No auth."}},"/api/v1/vault":{"get":{"parameters":[{"in":"query","name":"q","schema":{"type":"string"}},{"in":"query","name":"folder","schema":{"type":"string"}},{"in":"query","name":"tag","schema":{"type":"string"}},{"in":"query","name":"page","schema":{"type":"string"}},{"in":"query","name":"per_page","schema":{"type":"string"}}],"responses":{"200":{"description":"Page of vault docs + used_bytes/quota_bytes"}},"security":[{"bearer":[]}],"summary":"List your org's private vault documents"},"post":{"requestBody":{"content":{"multipart/form-data":{"schema":{"properties":{"file":{"description":"max 20MB, 500MB per org","format":"binary","type":"string"},"folder":{"type":"string"},"label":{"type":"string"},"tags":{"description":"comma separated","type":"string"}},"required":["file"],"type":"object"}}},"required":true},"responses":{"201":{"description":"Stored"},"400":{"description":"Validation"},"413":{"description":"File > 20MB or quota full"},"429":{"description":"Cap reached"}},"security":[{"bearer":[]}],"summary":"Upload a file to the private vault (encrypted at rest, AES-256-GCM); hash is registered on Base"}},"/api/v1/vault/{id}/download":{"get":{"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"File"},"404":{"description":"Not found or deleted"}},"security":[{"bearer":[]}],"summary":"Download a vault document (decrypted, hash re-verified; header X-Hash-Matches-Proof)"}}},"servers":[{"url":"https://proof.yhdblock.com"},{"description":"Ledger site (same API; public /api/v1/ledger endpoints)","url":"https://ledger.yhdblock.com"},{"description":"Credentials site (same API)","url":"https://credentials.yhdblock.com"}],"x-webhooks":{"ledger.published":{"description":"Same signing as proof.confirmed."},"proof.confirmed":{"description":"POST to your org webhook URL. Headers X-YHD-Timestamp, X-YHD-Signature: sha256=HMAC_SHA256(secret, timestamp + '.' + raw_body)."}}}