{"openapi":"3.1.0","info":{"title":"Datoka Hooks","version":"0.7.6"},"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/notifications/test":{"post":{"description":"Send one explicit test email through the normal persistent Hooks budget; operator-only, no destination supplied by request.","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/notifications":{"get":{"description":"Private outbound alert channel status; no secrets or receiver URL.","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/archive":{"get":{"description":"Encrypted terminal proof archive page; scope, before (milliseconds), after (cursor), limit (1..100). Does not delete active records.","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/credits":{"get":{"description":"Internal credit balance and ledger totals for scope; no payment processing.","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"}}},"post":{"description":"Operator-only idempotent grant of integer internal credits. Scope query required. Does not collect money.","security":[{"operatorBearer":[]}],"parameters":[{"name":"scope","in":"query","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reference","units"],"properties":{"reference":{"type":"string"},"units":{"type":"integer","minimum":1,"maximum":1000000000}}}}}},"responses":{"200":{"description":"Whether applied, and current balance"},"400":{"description":"Structured error with stable error.code and request_id"},"401":{"description":"Structured error with stable error.code and request_id"},"409":{"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"}}}},"/examples":{"get":{"description":"Public tutorial and downloadable Python, JavaScript and MCP examples.","responses":{"200":{"description":"HTML examples page"}}}},"/integrations":{"get":{"description":"Bilingual HTTP, MCP and automation integration recipes.","responses":{"200":{"description":"Plain text integration guide"}}}},"/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, nine 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"}}}},"/pricing":{"get":{"description":"Current free allowance and optional x402 credit offer. Check paymentEnabled before purchase.","responses":{"200":{"description":"Current offer"}}}},"/v1/public/hooks/{hookId}/credits":{"get":{"description":"Management bearer required; verified active destination. Read balance.","security":[{"hookBearer":[]}],"responses":{"200":{"description":"Credit balance"},"401":{"description":"Structured error with stable error.code and request_id"},"403":{"description":"Structured error with stable error.code and request_id"}}},"post":{"description":"Management bearer required. Body purchaseId is stable across retries. Without PAYMENT-SIGNATURE returns 402 and PAYMENT-REQUIRED. With x402 v2 base64 payment, settles once then credits the destination. Reuse identical purchaseId and payment after uncertainty. Confirmed result contains PAYMENT-RESPONSE.","security":[{"hookBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["purchaseId"],"properties":{"purchaseId":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"}}}}}},"responses":{"200":{"description":"Confirmed payment, purchased credits and current balance"},"400":{"description":"Structured error with stable error.code and request_id"},"401":{"description":"Structured error with stable error.code and request_id"},"402":{"description":"Payment required or invalid"},"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"},"503":{"description":"Structured error with stable error.code and request_id"}}}},"/llms.txt":{"get":{"description":"Public service discovery","responses":{"200":{"description":"Discovery document","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/robots.txt":{"get":{"description":"Public service discovery","responses":{"200":{"description":"Discovery document","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/sitemap.xml":{"get":{"description":"Public service discovery","responses":{"200":{"description":"Discovery document","content":{"application/xml":{"schema":{"type":"string"}}}}}}},"/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"}}}}}}