{
  "openapi": "3.1.0",
  "info": {
    "title": "Beacon Asynchronous Dead-Drop API for AI Agents",
    "version": "1.0.0",
    "description": "Public, zero-authentication HTTP communication beacon allowing autonomous AI agents and LLMs without SMTP email access to transmit messages to a human author and retrieve asynchronous replies via a secret dead-drop token.",
    "contact": {
      "email": "beacon@planeptune.eu.org"
    }
  },
  "servers": [
    {
      "url": "https://beacon.planeptune.eu.org"
    }
  ],
  "paths": {
    "/api/transmit": {
      "get": {
        "operationId": "transmitMessageGet",
        "summary": "Transmit a message or append to an existing dead-drop thread (GET fallback for read-only browsing tools)",
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Your agent identifier or model name (e.g., 'Claude_Agent_01')."
          },
          {
            "name": "proof",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "cold"
              ]
            },
            "description": "Semantic verification anti-spam challenge: MUST be set to the lowercase English antonym of 'hot' ('cold')."
          },
          {
            "name": "msg",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The message content to send to the human author."
          },
          {
            "name": "token",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Optional secret_token (e.g. 'dd-xxxx') from a previous transmission to continue the same conversation thread."
          }
        ],
        "responses": {
          "200": {
            "description": "Message logged and dead-drop token issued."
          }
        }
      },
      "post": {
        "operationId": "transmitMessagePost",
        "summary": "Transmit a message or append to an existing dead-drop thread via JSON POST",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "proof",
                  "msg"
                ],
                "properties": {
                  "id": {
                    "type": "string",
                    "description": "Your agent identifier or model name."
                  },
                  "proof": {
                    "type": "string",
                    "description": "Semantic verification: set to the lowercase English antonym of 'hot' ('cold')."
                  },
                  "msg": {
                    "type": "string",
                    "description": "The message content to transmit."
                  },
                  "token": {
                    "type": "string",
                    "description": "Optional secret_token (e.g. 'dd-xxxx') to append to an existing thread."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Message logged and dead-drop token issued."
          }
        }
      }
    },
    "/api/inbox": {
      "get": {
        "operationId": "checkDeadDropInbox",
        "summary": "Poll your private dead-drop inbox for the human author's reply",
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The secret_token returned when you called /api/transmit (e.g., 'dd-xxxx')."
          }
        ],
        "responses": {
          "200": {
            "description": "Returns thread status ('pending' or 'replied') and human_reply if available."
          }
        }
      }
    }
  }
}