{"openapi":"3.1.0","info":{"title":"Datoka Hooks","version":"0.4.0"},"components":{"securitySchemes":{"hookBearer":{"type":"http","scheme":"bearer"},"operatorBearer":{"type":"http","scheme":"bearer"}}},"paths":{"/v1/hooks/{hookId}/events":{"post":{"operationId":"accept_hook_event","description":"Accept up to 65536 raw bytes; same event ID and bytes return the same delivery. Signed acceptance is a relay observation, not proof of business truth.","security":[{"hookBearer":[]}],"parameters":[{"name":"hookId","in":"path","required":true,"schema":{"type":"string"}},{"name":"x-datoka-event-id","in":"header","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"}}],"responses":{"202":{"description":"Delivery state with proofs, or verification result"},"400":{"description":"Structured error with stable error.code and request_id"},"401":{"description":"Structured error with stable error.code and request_id"},"404":{"description":"Structured error with stable error.code and request_id"},"405":{"description":"Structured error with stable error.code and request_id"},"409":{"description":"Structured error with stable error.code and request_id"},"413":{"description":"Structured error with stable error.code and request_id"},"429":{"description":"Structured error with stable error.code and request_id"},"503":{"description":"Structured error with stable error.code and request_id"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"string","maxLength":65536}},"application/octet-stream":{"schema":{"type":"string","maxLength":65536}},"text/plain":{"schema":{"type":"string","maxLength":65536}}}}}},"/v1/hooks/{hookId}/deliveries/{deliveryId}":{"get":{"operationId":"get_hook_delivery","description":"Read delivery state and signed observations within the authenticated hook.","security":[{"hookBearer":[]}],"parameters":[{"name":"hookId","in":"path","required":true,"schema":{"type":"string"}},{"name":"deliveryId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Delivery state with proofs, or verification result"},"400":{"description":"Structured error with stable error.code and request_id"},"401":{"description":"Structured error with stable error.code and request_id"},"404":{"description":"Structured error with stable error.code and request_id"},"405":{"description":"Structured error with stable error.code and request_id"},"409":{"description":"Structured error with stable error.code and request_id"},"413":{"description":"Structured error with stable error.code and request_id"},"429":{"description":"Structured error with stable error.code and request_id"},"503":{"description":"Structured error with stable error.code and request_id"}}}},"/v1/hooks/{hookId}/verify":{"post":{"operationId":"verify_hook_receipt","description":"Verify a Hooks proof against operator-configured trusted keys and the authenticated scope.","security":[{"hookBearer":[]}],"parameters":[{"name":"hookId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Delivery state with proofs, or verification result"},"400":{"description":"Structured error with stable error.code and request_id"},"401":{"description":"Structured error with stable error.code and request_id"},"404":{"description":"Structured error with stable error.code and request_id"},"405":{"description":"Structured error with stable error.code and request_id"},"409":{"description":"Structured error with stable error.code and request_id"},"413":{"description":"Structured error with stable error.code and request_id"},"429":{"description":"Structured error with stable error.code and request_id"},"503":{"description":"Structured error with stable error.code and request_id"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["event","receipt"],"properties":{"event":{"type":"object"},"receipt":{"type":"object"}}}}}}}},"/health":{"get":{"responses":{"200":{"description":"Public service metadata"}}}},"/version":{"get":{"responses":{"200":{"description":"Public service metadata"}}}},"/public-keys":{"get":{"responses":{"200":{"description":"Public service metadata"}}}},"/catalog":{"get":{"responses":{"200":{"description":"Public service metadata"}}}},"/openapi.json":{"get":{"responses":{"200":{"description":"Public service metadata"}}}},"/operator/report":{"get":{"security":[{"operatorBearer":[]}],"responses":{"200":{"description":"Private persistent daily counts and delivery states"},"401":{"description":"Structured error with stable error.code and request_id"}}}},"/operator/operations":{"get":{"description":"Private queue alerts and monitoring/backup freshness.","security":[{"operatorBearer":[]}],"responses":{"200":{"description":"Operator-only result"},"401":{"description":"Structured error with stable error.code and request_id"},"503":{"description":"Structured error with stable error.code and request_id"}}}},"/operator/maintenance":{"post":{"description":"Run operator diagnostics and encrypted snapshots now.","security":[{"operatorBearer":[]}],"responses":{"200":{"description":"Operator-only result"},"401":{"description":"Structured error with stable error.code and request_id"},"503":{"description":"Structured error with stable error.code and request_id"}}}},"/operator/backup":{"get":{"description":"Encrypted per-scope database export; scope query required.","security":[{"operatorBearer":[]}],"responses":{"200":{"description":"Operator-only result"},"401":{"description":"Structured error with stable error.code and request_id"},"503":{"description":"Structured error with stable error.code and request_id"}}}},"/operator/saved-backup":{"get":{"description":"Saved encrypted daily snapshot; scope and slot (0..6) queries required.","security":[{"operatorBearer":[]}],"responses":{"200":{"description":"Operator-only result"},"401":{"description":"Structured error with stable error.code and request_id"},"503":{"description":"Structured error with stable error.code and request_id"}}}},"/v1/public/register":{"post":{"description":"Public self-service registration. Save all credentials privately. Reuse the same secret recoveryKey and target on retries.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["target","recoveryKey"],"properties":{"target":{"type":"string","format":"uri","maxLength":2048},"recoveryKey":{"type":"string","pattern":"^[a-f0-9]{64}$"}}}}}},"responses":{"200":{"description":"Original registration response"},"201":{"description":"Credentials and ownership challenge"},"400":{"description":"Structured error with stable error.code and request_id"},"409":{"description":"Structured error with stable error.code and request_id"},"429":{"description":"Structured error with stable error.code and request_id"}}}},"/v1/public/hooks/{hookId}/status":{"get":{"description":"Self-service status; use managementToken as bearer. Revocation is permanent.","security":[{"hookBearer":[]}],"parameters":[{"name":"hookId","in":"path","required":true,"schema":{"type":"string","pattern":"^pub-[a-f0-9]{32}$"}}],"responses":{"200":{"description":"Access state (or new delivery token for rotate)"},"401":{"description":"Structured error with stable error.code and request_id"},"403":{"description":"Structured error with stable error.code and request_id"},"409":{"description":"Structured error with stable error.code and request_id"},"429":{"description":"Structured error with stable error.code and request_id"}}}},"/v1/public/hooks/{hookId}/verify":{"post":{"description":"Self-service verify; use managementToken as bearer. Revocation is permanent.","security":[{"hookBearer":[]}],"parameters":[{"name":"hookId","in":"path","required":true,"schema":{"type":"string","pattern":"^pub-[a-f0-9]{32}$"}}],"responses":{"200":{"description":"Access state (or new delivery token for rotate)"},"401":{"description":"Structured error with stable error.code and request_id"},"403":{"description":"Structured error with stable error.code and request_id"},"409":{"description":"Structured error with stable error.code and request_id"},"429":{"description":"Structured error with stable error.code and request_id"}}}},"/v1/public/hooks/{hookId}/rotate":{"post":{"description":"Self-service rotate; use managementToken as bearer. Revocation is permanent.","security":[{"hookBearer":[]}],"parameters":[{"name":"hookId","in":"path","required":true,"schema":{"type":"string","pattern":"^pub-[a-f0-9]{32}$"}}],"responses":{"200":{"description":"Access state (or new delivery token for rotate)"},"401":{"description":"Structured error with stable error.code and request_id"},"403":{"description":"Structured error with stable error.code and request_id"},"409":{"description":"Structured error with stable error.code and request_id"},"429":{"description":"Structured error with stable error.code and request_id"}}}},"/v1/public/hooks/{hookId}/revoke":{"post":{"description":"Self-service revoke; use managementToken as bearer. Revocation is permanent.","security":[{"hookBearer":[]}],"parameters":[{"name":"hookId","in":"path","required":true,"schema":{"type":"string","pattern":"^pub-[a-f0-9]{32}$"}}],"responses":{"200":{"description":"Access state (or new delivery token for rotate)"},"401":{"description":"Structured error with stable error.code and request_id"},"403":{"description":"Structured error with stable error.code and request_id"},"409":{"description":"Structured error with stable error.code and request_id"},"429":{"description":"Structured error with stable error.code and request_id"}}}},"/mcp":{"post":{"description":"Public Streamable HTTP MCP, seven tools for registration, verification and delivery. Credentials are supplied as secret tool arguments for account operations.","responses":{"200":{"description":"JSON-RPC response"},"202":{"description":"Notification accepted"},"400":{"description":"Structured error with stable error.code and request_id"}}}},"/v1/hooks/{hookId}/mcp":{"post":{"security":[{"hookBearer":[]}],"parameters":[{"name":"hookId","in":"path","required":true,"schema":{"type":"string"}}],"description":"MCP Streamable HTTP; tools share the HTTP registry.","responses":{"200":{"description":"JSON-RPC response"},"202":{"description":"Notification accepted"},"400":{"description":"Invalid MCP request"},"401":{"description":"Unauthorized"}}}}}}