{
  "openapi": "3.1.0",
  "info": { "title": "Toolbooth", "version": "1.0.0", "description": "Pay-per-call tools for AI agents over x402. Paid operations answer 402 with a PAYMENT-REQUIRED header until a valid payment is attached." },
  "servers": [{ "url": "https://toolbooth.dev" }],
  "paths": {
    "/v1/inboxes": {
      "post": {
        "operationId": "createInbox",
        "summary": "Create a webhook inbox (paid, x402)",
        "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "ttl_hours": { "type": "integer", "minimum": 1, "maximum": 168, "default": 168 } }, "additionalProperties": false } } } },
        "responses": {
          "201": { "description": "Inbox created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Inbox" } } } },
          "402": { "description": "Payment required; see the PAYMENT-REQUIRED header (base64 JSON)" },
          "400": { "description": "Invalid ttl_hours" }
        }
      }
    },
    "/h/{inbox_id}": {
      "post": {
        "operationId": "deliver",
        "summary": "Deliver a callback (free, unauthenticated; also PUT and PATCH)",
        "parameters": [{ "name": "inbox_id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "requestBody": { "content": { "*/*": { "schema": { "type": "string", "format": "binary", "maxLength": 262144 } } } },
        "responses": { "202": { "description": "Stored" }, "404": { "description": "No such inbox or expired" }, "413": { "description": "Over 256 KB" }, "429": { "description": "Inbox full (100 messages)" } }
      }
    },
    "/v1/inboxes/{inbox_id}/messages": {
      "get": {
        "operationId": "listMessages",
        "summary": "Read deliveries, optionally long-polling",
        "security": [{ "inboxToken": [] }],
        "parameters": [
          { "name": "inbox_id", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "after", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Return messages with seq greater than this" },
          { "name": "wait", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 20, "default": 0 }, "description": "Seconds to wait for a new message if none are pending" }
        ],
        "responses": { "200": { "description": "Messages", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageList" } } } }, "404": { "description": "Not found, expired, or wrong token" } }
      }
    },
    "/v1/inboxes/{inbox_id}": {
      "delete": {
        "operationId": "deleteInbox",
        "security": [{ "inboxToken": [] }],
        "parameters": [{ "name": "inbox_id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "204": { "description": "Deleted" }, "404": { "description": "Not found or wrong token" } }
      }
    }
  },
  "components": {
    "securitySchemes": { "inboxToken": { "type": "http", "scheme": "bearer" } },
    "schemas": {
      "Inbox": { "type": "object", "required": ["inbox_id", "callback_url", "token", "messages_url", "expires_at"], "properties": {
        "inbox_id": { "type": "string" }, "callback_url": { "type": "string", "format": "uri" }, "token": { "type": "string" },
        "messages_url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" },
        "limits": { "type": "object", "properties": { "max_messages": { "type": "integer" }, "max_body_bytes": { "type": "integer" } } } } },
      "MessageList": { "type": "object", "properties": {
        "expires_at": { "type": "string", "format": "date-time" }, "next_after": { "type": "integer" },
        "messages": { "type": "array", "items": { "type": "object", "properties": {
          "seq": { "type": "integer" }, "received_at": { "type": "string", "format": "date-time" }, "method": { "type": "string" },
          "content_type": { "type": ["string", "null"] }, "headers": { "type": "object" }, "size": { "type": "integer" },
          "body": { "type": "string" }, "body_base64": { "type": "string" } } } } } }
    }
  }
}