{"openapi":"3.1.0","info":{"title":"HookMPP API","version":"0.1.0","description":"Disposable webhook inboxes for autonomous agents, paid for per inbox with MPP.","contact":{"url":"https://hookmpp.dev"},"x-guidance":"Create an inbox with POST /api/inboxes, satisfy its runtime MPP challenge, then retain the returned webhook_url, events_url, and secret read_token. Webhook delivery is public. Read events with Authorization: Bearer <read_token>, advance using next_cursor, and treat the runtime challenge and creation response as authoritative for payment terms and limits."},"servers":[{"url":"https://hookmpp.dev"}],"x-service-info":{"categories":["web","compute"],"docs":{"homepage":"https://hookmpp.dev","apiReference":"https://hookmpp.dev/openapi.json","llms":"https://hookmpp.dev/llms.txt"},"profile":"quick","profiles":["quick","standard","extended"]},"paths":{"/api/inboxes":{"post":{"operationId":"createInbox","summary":"Create a prepaid ephemeral webhook inbox","parameters":[{"name":"profile","in":"query","required":false,"description":"Purchased inbox capability; omitted defaults to quick.","schema":{"type":"string","enum":["quick","standard","extended"],"default":"quick"}}],"x-payment-info":{"offers":[{"amount":"10000","currency":"0x20c0000000000000000000000000000000000000","description":"Create a quick HookMPP inbox","intent":"charge","method":"tempo","profile":"quick"},{"amount":"50000","currency":"0x20c0000000000000000000000000000000000000","description":"Create a standard HookMPP inbox","intent":"charge","method":"tempo","profile":"standard"},{"amount":"200000","currency":"0x20c0000000000000000000000000000000000000","description":"Create a extended HookMPP inbox","intent":"charge","method":"tempo","profile":"extended"}],"price":{"mode":"dynamic","currency":"USD","min":"0.01","max":"0.20"},"protocols":[{"mpp":{"method":"tempo","intent":"charge","currency":"0x20c0000000000000000000000000000000000000"}}]},"responses":{"201":{"$ref":"#/components/responses/InboxCreated"},"400":{"$ref":"#/components/responses/BadRequest"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/i/{inboxId}":{"parameters":[{"name":"inboxId","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-f]{64}$"}}],"patch":{"operationId":"deliverWebhookPatch","summary":"Deliver a webhook payload with PATCH","security":[],"requestBody":{"required":false,"content":{"*/*":{"schema":{"type":"string","description":"Raw webhook body, limited to 65536 bytes after transfer decoding.","x-max-bytes":65536}}}},"responses":{"202":{"$ref":"#/components/responses/WebhookAccepted"},"400":{"$ref":"#/components/responses/BadRequest"},"409":{"$ref":"#/components/responses/CapacityReached"},"410":{"$ref":"#/components/responses/Gone"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"},"431":{"$ref":"#/components/responses/HeadersTooLarge"}}},"post":{"operationId":"deliverWebhookPost","summary":"Deliver a webhook payload with POST","security":[],"requestBody":{"required":false,"content":{"*/*":{"schema":{"type":"string","description":"Raw webhook body, limited to 65536 bytes after transfer decoding.","x-max-bytes":65536}}}},"responses":{"202":{"$ref":"#/components/responses/WebhookAccepted"},"400":{"$ref":"#/components/responses/BadRequest"},"409":{"$ref":"#/components/responses/CapacityReached"},"410":{"$ref":"#/components/responses/Gone"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"},"431":{"$ref":"#/components/responses/HeadersTooLarge"}}},"put":{"operationId":"deliverWebhookPut","summary":"Deliver a webhook payload with PUT","security":[],"requestBody":{"required":false,"content":{"*/*":{"schema":{"type":"string","description":"Raw webhook body, limited to 65536 bytes after transfer decoding.","x-max-bytes":65536}}}},"responses":{"202":{"$ref":"#/components/responses/WebhookAccepted"},"400":{"$ref":"#/components/responses/BadRequest"},"409":{"$ref":"#/components/responses/CapacityReached"},"410":{"$ref":"#/components/responses/Gone"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"},"431":{"$ref":"#/components/responses/HeadersTooLarge"}}}},"/api/inboxes/{inboxId}/events":{"get":{"operationId":"listInboxEvents","summary":"Read events using the secret token returned at creation","parameters":[{"name":"inboxId","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-f]{64}$"}},{"name":"after","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0}},{"name":"wait","in":"query","required":false,"description":"Wait up to this many seconds for an event before returning an empty page.","schema":{"type":"integer","minimum":0,"maximum":30,"default":0}}],"security":[{"bearerAuth":[]}],"responses":{"200":{"$ref":"#/components/responses/EventsListed"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/AuthenticationRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"410":{"$ref":"#/components/responses/Gone"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ReadServiceUnavailable"}}}}},"components":{"schemas":{"Problem":{"type":"object","additionalProperties":false,"required":["type","status","title","detail"],"properties":{"type":{"type":"string","description":"Problem type URI."},"status":{"type":"integer","minimum":400,"maximum":599},"title":{"type":"string"},"detail":{"type":"string"}}},"InboxLimits":{"type":"object","additionalProperties":false,"required":["events","event_bytes","header_bytes","total_bytes"],"properties":{"events":{"type":"integer","enum":[25,100,500]},"event_bytes":{"type":"integer","const":65536,"description":"Maximum decoded bytes in one webhook body.","x-max-bytes":65536},"header_bytes":{"type":"integer","const":16384,"description":"Maximum bytes of sanitized header names and values stored per event.","x-max-bytes":16384},"total_bytes":{"type":"integer","enum":[1048576,8388608,33554432],"description":"Maximum stored envelope, header, and body bytes across the inbox.","x-max-bytes":33554432}}},"InboxCreated":{"type":"object","additionalProperties":false,"required":["id","profile","webhook_url","events_url","read_token","expires_at","limits"],"properties":{"id":{"type":"string","pattern":"^[0-9a-f]{64}$"},"profile":{"type":"string","enum":["quick","standard","extended"]},"webhook_url":{"type":"string","format":"uri"},"events_url":{"type":"string","format":"uri"},"read_token":{"type":"string","description":"Secret bearer credential returned only at creation."},"expires_at":{"type":"string","format":"date-time"},"limits":{"$ref":"#/components/schemas/InboxLimits"}}},"WebhookAccepted":{"type":"object","additionalProperties":false,"required":["accepted","event_id","received_at"],"properties":{"accepted":{"type":"boolean","const":true},"event_id":{"type":"string","format":"uuid"},"received_at":{"type":"string","format":"date-time"}}},"InboxEvent":{"type":"object","additionalProperties":false,"required":["body","headers","id","method","receivedAt","sequence","size","storageSize","url"],"properties":{"body":{"type":"string","description":"UTF-8 decoded webhook body."},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"Sanitized stored headers; credential values are redacted."},"id":{"type":"string","format":"uuid"},"method":{"type":"string","enum":["POST","PUT","PATCH"]},"receivedAt":{"type":"integer","description":"Unix timestamp in milliseconds."},"sequence":{"type":"integer","minimum":1},"size":{"type":"integer","minimum":0,"description":"Decoded body size in bytes."},"storageSize":{"type":"integer","minimum":0,"description":"Complete stored event size in bytes."},"url":{"type":"string","format":"uri"}}},"EventsListed":{"type":"object","additionalProperties":false,"required":["events","next_cursor","expires_at"],"properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/InboxEvent"}},"next_cursor":{"type":"integer","minimum":0},"expires_at":{"type":"string","format":"date-time"}}}},"responses":{"InboxCreated":{"description":"Inbox created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboxCreated"}}}},"PaymentRequired":{"description":"Payment required","headers":{"WWW-Authenticate":{"required":true,"schema":{"type":"string"},"description":"MPP payment challenge."}}},"ServiceUnavailable":{"description":"Payment service unavailable","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"ReadServiceUnavailable":{"description":"Inbox read temporarily unavailable","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"WebhookAccepted":{"description":"Webhook accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookAccepted"}}}},"EventsListed":{"description":"Events after the supplied cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventsListed"}}}},"BadRequest":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"AuthenticationRequired":{"description":"Read token required","headers":{"WWW-Authenticate":{"required":true,"schema":{"type":"string"}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Forbidden":{"description":"Invalid read token","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"CapacityReached":{"description":"Inbox capacity reached","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Gone":{"description":"Inbox unavailable or expired","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"PayloadTooLarge":{"description":"Webhook body too large","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"HeadersTooLarge":{"description":"Stored webhook headers too large","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"TooManyRequests":{"description":"Request rate or concurrency limit exceeded","headers":{"Retry-After":{"required":true,"schema":{"type":"integer","minimum":1}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}},"x-payment-info":{"profiles":["quick","standard","extended"],"method":"tempo"},"x-hookmpp-profiles":{"quick":{"ttl_seconds":900,"events":25,"event_bytes":65536,"header_bytes":16384,"total_bytes":1048576},"standard":{"ttl_seconds":7200,"events":100,"event_bytes":65536,"header_bytes":16384,"total_bytes":8388608},"extended":{"ttl_seconds":86400,"events":500,"event_bytes":65536,"header_bytes":16384,"total_bytes":33554432}}}